Virtual File System

Overview

The Kryon Virtual File System (VFS) is a path-based namespace where every value is accessible through a file path. All operations—reading values, writing properties, handling events—are performed through paths.

This enables Zero-API remote control — standard file operations on URLs control your UI.

Path Types

Absolute Paths

Start with / and specify the full path from root:

/dev/draw      // Drawing device
/dev/wctl      // Window control device
/dev/mouse     // Mouse input device
/dev/timer     // Timer device
/dev/cons      // Console output
/meta/title    // Metadata title
/env/w         // Environment width

Relative Paths

Start with ./ and refer to the current VFS node:

./radius       // Current node's radius
./color        // Current node's color
./dir          // Current node's direction

Parent Paths

Start with ../ and refer to the parent VFS node:

../speed       // Parent's speed
../size        // Parent's size
../title       // Parent's title

Root-Level Blocks Create VFS Folders

The const and var blocks create VFS folders at the root level.

const Blocks

Creates a read-only VFS folder:

const meta {
    title "Inner Breeze"
    ver   "alpha"
    by    "waozi"
    id    "xyz.waozi.inbe"
}

Accessible at:

/meta/title  (read-only)
/meta/ver    (read-only)
/meta/by     (read-only)
/meta/id     (read-only)

var Blocks

Creates a read-write VFS folder:

var env {
    w       200
    h       400
    breaths 30
    rounds  3
    pause   0
}

Accessible at:

/env/w       (read-write)
/env/h       (read-write)
/env/breaths (read-write)
/env/rounds  (read-write)
/env/pause   (read-write)

Definitions Create Numbered Instances

Each call to a def creates a new numbered VFS folder.

def button {
    write /dev/draw [ rect %pos[0] %pos[1] %size[0] %size[1] 0xCCCCCC ]
    %action
}

button { pos [ 10 10 ] size [ 80 30 ] action { ... } }  // Creates /0
button { pos [ 10 50 ] size [ 80 30 ] action { ... } }  // Creates /1
button { pos [ 10 90 ] size [ 80 30 ] action { ... } }  // Creates /2

Nested definitions create deeper paths:

def window {
    def button { ... }
    button { pos [ 10 10 ] size [ 80 30 ] }  // Creates /0/0
    button { pos [ 10 50 ] size [ 80 30 ] }  // Creates /0/1
}

Device Files

Device files in /dev/* provide I/O operations.

Path Resolution in Control Blocks

Control blocks like action, logic, tick, enter, exit, down do not create new VFS folders. Relative paths inside these blocks refer to the parent definition.

def circle {
    write /dev/draw [ circ %center[0] %center[1] ./radius %color ]

    logic {
        listen /dev/timer {
            tick 50 {
                // ./radius refers to the circle's radius, not the timer's
                write ./radius [ + ./radius 1 ]
            }
        }
    }
}

This means ./radius inside the tick block correctly refers to the circle's radius value.

Access via CoAP

VFS paths are accessible through CoAP for network control.

Reading Values

coap-client get coap://192.168.1.100/env/w
coap-client get coap://192.168.1.100/0/radius

Writing Values

# Set env/w to 240 (0x00F0 in big-endian)
echo -n -e "\x00\xF0" | coap-client put coap://192.168.1.100/env/w

# Set 0/radius to 50 (0x0032 in big-endian)
echo -n -e "\x00\x32" | coap-client put coap://192.168.1.100/0/radius

See CoAP documentation for details on payload formats.

Complete Example

Source (.kry)

const meta {
    title "MyApp"
    ver "1.0"
}

var env {
    w 200
    h 400
}

def circle {
    write /dev/draw [ circ %center[0] %center[1] ./radius %color ]
}

circle {
    center [ 100 100 ]
    radius 50
    color 0xFF0000
}

Generated VFS Structure

Runtime Implementation

The VFS is implemented differently per platform.

ESP32 (kryesp)

• CoAP server on port 5683
• FreeRTOS queue for thread-safe updates
• Direct memory access to UI state

Plan 9 (krysrv)

• 9P filesystem mounted at /mnt/kry
• CoAP to 9P bridge
• Standard file I/O operations

Linux (plan9port)

• CoAP server for network access
• VFS at /tmp/kry for local access
• X11 or framebuffer graphics

Web (kryweb)

• WebSocket bridge
• JSON message format
• Browser-based UI

Error Handling

Best Practices

• Use const for immutable data: Metadata, sprites, configuration
• Use var for runtime state: Animation values, counters, flags
• Use def for reusable components: Buttons, circles, custom widgets
• Use fn for inline helpers: Drawing helpers, calculations
• Use relative paths: ./value is more portable than absolute paths
• Document your VFS: Keep a list of exported paths for client developers