Vfs

An execution context: another machine, container, or privilege level.

Filesystem access, external programs, environment, working directory, target system information, and security identity all follow the selected context.

Constructor

`Vfs func`

Runs func on a background stream and connects to a VFS server over its input and output.

func must launch a program that speaks the VFS protocol. The --stdio mode reads the protocol from standard input and writes it to standard output, so the launched program must not write anything else there; diagnostics may use standard error. If the launcher exits before the handshake completes, its error is reported instead of the resulting VFS disconnect.

The Vfs retains the background stream for its lifetime.

Parameters

Name	Type	Description
`func`	`(() -> Value)`	VFS server launcher.

Example

let remote = Vfs do run ssh host dolang-vfs --stdio

Class Methods

`unix_socket path … -> Vfs`

Connects to a running dolang-vfs daemon on Unix.

The socket path is resolved in the active VFS context, so this can reach a daemon visible only from another remote or container VFS. A direct non-Unix context reports that Unix VFS connections are unsupported.

The working directory in which the dolang-vfs process started becomes the context's initial working directory.

Parameters

Name	Type	Description
`path`	`fs.Path`	Unix socket path.
`:key?`	`(Str \| Bin)`	Pre-shared key that both ends prove knowledge of during the handshake.

`:key`

Supply it when the socket's permissions cannot identify the peer. An agent inside a container binds its socket 0666, because the uid that will connect is not knowable in advance, leaving it reachable by anything that can traverse the containing directory.

The agent must have been started with --key-stdin and given the same key, and the requirement is mutual: a key here fails against an agent without one, and an agent expecting one refuses a connection without it. Keys must be at least 16 bytes and must carry sufficient entropy on their own, so generate one with rand.string rather than choosing it.

This authenticates the connection; it does not encrypt or integrity-protect the session that follows.

Errors

Exception	Condition
`sys.NotFoundError`	The socket path does not exist
`sys.ConnectionRefusedError`	The endpoint is unavailable
`sys.PermissionDeniedError`	Authentication fails or only one endpoint was configured with a key
`sys.InvalidInputError`	The key is shorter than 16 bytes

Example

let a = Vfs.unix_socket /tmp/agent/socket

Authenticated, with a freshly generated key:

let key = rand.string 32
let a = Vfs.unix_socket /tmp/agent/socket :key

`windows_admin … -> Vfs`

Launches an elevated copy of the active Windows VFS target's current executable.

This can cross an existing VFS connection, such as a connection from WSL to its Windows host. The target resolves its own executable; callers cannot select another program. When the executable is dolang.exe, --vfs is inserted to select its VFS entrypoint; a standalone dolang-vfs.exe is launched directly.

Windows displays a User Account Control prompt, and cancelling it raises a system error.

Windows does not reliably allow the elevated process to use console handles from the non-elevated caller, so console programs using inherited terminal I/O may hang, fail, or produce no output. Redirected and captured output uses ordinary handles and works across the elevated VFS boundary.

Parameters

Name	Type	Description
`:cd?`	`fs.Path`	Initial working directory. Defaults to the calling strand's.
`:env?`	`Dict[Str \| Sym, Value]`	Environment overrides. Keys may be strings or symbols; `nil` unsets a variable and `:INHERIT:` captures the calling strand's current value.

Example

let admin = Vfs.windows_admin()

Methods

`stop()`

Sends a stop request to the connected VFS server.

A function-backed Vfs then closes and joins its launcher stream. On Windows, it also waits for the elevated process to exit.

`with[R] func -> R`

Runs a function in this context.

Each entry starts from the context's initial working directory. That value is fixed when the Vfs is created, so moving the handle out of its original working-directory scope does not change it, and a cd inside the block affects that entry but not the starting directory of later ones.

Entering the context reroutes the VFS-aware operations:

External programs run through the VFS daemon
env reads and writes that context's environment
cd changes that context's working directory
fs operations use that context's filesystem view
sys reports that context's operating system and CPU
security reports that context's identity

Everything else stays in the interpreter process unless its documentation says otherwise -- network clients and native resources especially.

Parameters

Name	Type	Description
`func`	`(() -> R)`	Function to run.

Example

a.with do
  run ls /
  run cat /etc/os-release