shell::config-status
functionReport the last configuration hot-reload outcome: last_outcome (applied|rejected), last_error, and rejected_reloads (count since boot). A rejected outcome or non-zero count means a stored config was refused and shell is enforcing an older policy than the central store. Takes no arguments.
last_errorstring
Build error from the most recent rejected reload (why it was refused).
last_outcomeone of*required
Outcome of the most recent hot-reload attempt, exposed via `shell::config-status`.
one of (2)
variant 1
valuestringenum: applied
variant 2
valuestringenum: rejected
rejected_reloadsinteger· uint64*requiredmin 0
Cumulative count of rejected reloads since boot (never reset).
Run an allowlisted command in the foreground and return its full output. Put the program name in `command` (string) and arguments in `args` (string[]) — do NOT pass argv as an array in `command`. `timeout_ms` is capped at the configured max; negative/fractional values fall back to the default. `target` defaults to the host; pass { kind: "sandbox", sandbox_id } to run in a microVM. Optional host-only `cwd` scopes this call to a directory (jail-confined exactly like shell::fs::* paths; escaping it is S215), optional `env` (object) sets per-call values — but only for keys already in the operator's env.allow list and never for PATH/IFS/HOME/LD_*/DYLD_* or other loader/lookup and interpreter-startup keys (those reject S210) — and optional host-only `stdin` (string) is written to the program's standard input (use it for `tee`, `patch`, or any stdin filter instead of a shell heredoc). cwd/env/stdin on a sandbox target reject S210. Backend errors return { code, message }; common: S216 host exec error, S300 VM boot failed, S200 in-VM failure. argv-parse and allowlist/denylist rejections are plain-string messages naming the violation.
argsstring[]
Arguments passed to the program, in order. Every element must be a string; non-string elements are rejected by index. `None` (or `args: null` / absent) means "tokenize `command` via shell-words"; `Some(_)` (including the empty vec) means "use args verbatim, no shell-words." See `parse_argv` in `crate::exec::host`.
commandstring*required
Program name (matched against the allowlist by basename or exact path). Must be a string — split arguments into `args`, do not pass argv as an array here.
cwdstring
Optional working directory for this call (host target only). Confined to the fs jail exactly like `shell::fs::*` paths: jail-relative when `fs.host_roots` are set (else absolute), canonicalized, and must resolve inside a jail root and miss the denylist — a path that escapes returns S215. Must already exist and be a directory. Omit to use the configured `working_dir` (unchanged default). Rejected (S210) on a sandbox target.
envobject
Optional per-call environment values (host target only). A key may be set ONLY if the operator listed it in `env.allow`, and NEVER for an exec-hijacking key (PATH, IFS, HOME, LD_*/DYLD_*, and other loader/lookup and interpreter-startup keys — see DANGEROUS_ENV_KEYS) — those are rejected even if allowlisted. Supplying a key that is not in `env.allow`, or any dangerous key, rejects the WHOLE call (S210) naming the offending key; the env is never silently dropped. Permitted values override what would otherwise be forwarded for that key. Rejected (S210) on a sandbox target.
stdinstring
Optional bytes written to the program's standard input, followed by EOF. Use this to pipe content to a command that reads stdin (`tee`, `patch`, `cat`, a filter) instead of wrapping it in a shell heredoc. Omit to leave stdin closed (`/dev/null`, the default). HOST target only — rejected (S210) on a sandbox target, like cwd/env.
targetall of
Where to run the command. Defaults to the host worker; pass `{ kind: "sandbox", sandbox_id }` to forward the call to a microVM.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
timeout_msinteger· uint64min 0
Per-call timeout override, milliseconds. Capped at `cfg.max_timeout_ms`. Negative or fractional values silently fall back to `cfg.default_timeout_ms` (loose wire semantic, preserved on purpose).
duration_msinteger· uint64*requiredmin 0
stderr_truncatedboolean*required
stdout_truncatedboolean*required
timed_outboolean*required
Spawn an allowlisted command as a background job; returns { job_id, argv } immediately. Same payload as shell::exec (command + args, do NOT pass argv as an array), including the optional host-only `cwd` (jail-confined; escape is S215), `env` (only keys in the operator's env.allow list, never PATH/IFS/HOME/LD_*/DYLD_* or other loader/lookup and interpreter-startup keys), and `stdin` (string written to the job's stdin); violations and cwd/env/stdin on a sandbox target reject with an S210 message. Poll with shell::status, terminate with shell::kill, list with shell::list. Host background jobs ignore the per-call timeout_ms and run until they exit or shell::kill terminates them; set the operator config `max_bg_timeout_ms` (0 = unbounded, the default) to force-kill a runaway job after that long. Spawn-time failures (argv-parse, allowlist/denylist, cwd/env gating, spawn, concurrency cap) are plain-string messages naming the violation; once spawned, per-job failures surface through shell::status (the job record's status/stderr), not this call's return.
argsstring[]
Arguments passed to the program. See [`ExecRequest::args`]. `None` (or `args: null` / absent) means "tokenize `command` via shell-words"; `Some(_)` (including the empty vec) means "use args verbatim, no shell-words." See `parse_argv` in `crate::exec::host`.
commandstring*required
Program name. See [`ExecRequest::command`].
cwdstring
Optional working directory for this job (host target only). Same jail confinement and rules as [`ExecRequest::cwd`]: canonicalized, must resolve inside a jail root (S215 on escape) and be an existing directory. Rejected (S210) on a sandbox target.
envobject
Optional per-call environment values (host target only). Same gating as [`ExecRequest::env`]: a key must be in `env.allow` and must not be an exec-hijacking key (PATH, IFS, HOME, LD_*/DYLD_*, and other loader/lookup and interpreter-startup keys — see DANGEROUS_ENV_KEYS); any violation rejects the whole call (S210). Rejected (S210) on a sandbox target.
stdinstring
Optional bytes written to the job's standard input, then EOF. See [`ExecRequest::stdin`]. HOST target only — rejected (S210) on a sandbox target.
targetall of
Where to run. See [`ExecRequest::target`].
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
timeout_msinteger· uint64min 0
Per-call timeout. Host-targeted background jobs IGNORE `timeout_ms`; sandbox-targeted ones forward it through `cfg.resolve_timeout`.
Change permissions. `mode` is an octal string like "0644". `uid`/`gid` optionally chown. `recursive: true` walks the tree (symlinks skipped). Returns { entries_changed, path, recursive }. Errors return { code, message }; common: S210 bad mode, S211 not found, S215 jail/denylist.
gidinteger· uint32min 0
Optional chown to this numeric gid.
modestring*required
Octal permission string, e.g. "0755".
pathstring*required
Jail-relative when fs.host_roots are set, else absolute.
recursiveboolean
Apply mode/owner change to all files under the path recursively.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
uidinteger· uint32min 0
Optional chown to this numeric uid.
entries_changedinteger· uint64*requiredmin 0
Number of filesystem entries whose mode/owner changed.
pathstring
The path that was targeted. Empty for sandbox targets.
recursiveboolean
Whether the change was applied recursively. Host only.
Search file contents. `pattern` is a Rust regex (RE2-like). `recursive` defaults true. `include_glob`/`exclude_glob` filter paths. Returns { matches, truncated }. Errors return { code, message }; common: S217 bad regex, S215 jail/denylist.
exclude_globstring[]
Glob filters excluding file paths from the search.
ignore_caseboolean
Match pattern case-insensitively.
include_globstring[]
Glob filters restricting which file paths are searched.
max_line_bytesinteger· uint64min 0
Skip lines longer than this many bytes (default 4 096).
max_matchesinteger· uint64min 0
Stop collecting matches after this many results (default 10 000).
pathstring*required
Jail-relative when fs.host_roots are set, else absolute.
patternstring*required
Rust regex (RE2-like) matched against each line.
recursiveboolean
Descend into subdirectories (default true).
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
matchesobject[]*required
All collected match locations up to `max_matches`.
lineinteger· uint64*requiredmin 0
truncatedboolean*required
True when the result was capped by `max_matches` or `max_line_bytes`.
List directory contents. `path` is relative to the primary fs jail root (the first fs.host_roots entry) when set, otherwise absolute. `target` defaults to host; pass { kind: "sandbox", sandbox_id } to run in a microVM. Errors return { code, message }; common: S210 bad path, S211 not found, S212 not a directory, S215 jail/denylist.
pathstring*required
Jail-relative when fs.host_roots are set, else absolute.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
entriesobject[]*required
Metadata for each entry in the directory.
is_symlinkboolean*required
mtimeinteger· int64*required
sizeinteger· uint64*requiredmin 0
Create a directory. `mode` is an octal string like "0755". `parents: true` creates missing parents and is idempotent. Returns { created, path, already_existed }. Errors return { code, message }; common: S210 bad mode, S213 exists, S215 jail/denylist.
modestring
Octal permission string, e.g. "0755".
parentsboolean
Create missing parent directories.
pathstring*required
Jail-relative when fs.host_roots are set, else absolute.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
already_existedboolean
True when the path already existed and `parents` was set. Host only; sandbox targets default this to false (not a signal there).
createdboolean*required
True when a new directory was created; false when it already existed (only possible with `parents: true`, which is idempotent).
pathstring
The directory path that was targeted. Empty for sandbox targets.
Move/rename a path. `overwrite: true` allows replacing an existing dst. Returns { moved, src, dst, overwrote }. Errors return { code, message }; common: S211 src not found, S213 dst exists, S215 jail/denylist.
dststring*required
Destination path; jail-relative when fs.host_roots are set, else absolute.
overwriteboolean
Replace an existing destination instead of returning an error.
srcstring*required
Source path; jail-relative when fs.host_roots are set, else absolute.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
dststring
Destination path. Empty for sandbox targets.
movedboolean*required
True when the move/rename succeeded.
overwroteboolean
True when an existing destination was overwritten. Host only (sandbox targets default this to false, not a signal there). Best-effort: derived from a pre-rename existence check, so under a concurrent writer racing the destination it may under-report (and an `overwrite:false` move can still replace a file created in that window).
srcstring
Source path. Empty for sandbox targets.
Stream a file from a path. Returns a ContentRef the caller reads from, plus size/mode/mtime. Errors return { code, message }; common: S211 not found, S212 path is a directory, S215 jail/denylist, S218 file exceeds max_read_bytes, S216 channel/IO error.
pathstring*required
Jail-relative when fs.host_roots are set, else absolute.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
contentall of*required
Channel reference for streaming the file content back to the caller.
all of (1)
variant 1
access_keystring*required
Secret key that authorises access to this channel.
channel_idstring*required
Opaque identifier for the open stream channel.
directionall of
Direction of data flow: "read" (consume) or "write" (produce).
… expand 1 nestedcollapse
all of (1)
variant 1
valuestringenum: read, write
modestring*required
Octal permission string of the file, e.g. "0644".
mtimeinteger· int64*required
Last-modified time as a Unix timestamp (seconds).
sizeinteger· uint64*requiredmin 0
File size in bytes at the time of the read.
Remove a path. `recursive: true` is required to delete a non-empty directory. Returns { removed, path, was_present }. Errors return { code, message }; common: S211 not found, S214 dir not empty (pass recursive), S215 jail/denylist.
pathstring*required
Jail-relative when fs.host_roots are set, else absolute.
recursiveboolean
Required to delete a non-empty directory.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
pathstring
The path that was targeted. Empty for sandbox targets.
removedboolean*required
True when the path was removed.
was_presentboolean
True when the path existed before removal. Host only; sandbox targets default this to false, which does NOT mean the path was absent.
Find-and-replace across files. `pattern` is a Rust regex by default (set regex:false for a literal). Provide either `files` (explicit list) or `path` (+ recursive). Returns { results, total_replacements }. Errors return { code, message }; common: S217 bad regex, S211 not found, S215 jail/denylist.
exclude_globstring[]
Glob filters excluding file paths from editing.
filesstring[]
Explicit list of file paths to edit; provide either this or `path`, not both.
first_onlyboolean
Replace only the first match per file instead of all matches.
ignore_caseboolean
Match pattern case-insensitively.
include_globstring[]
Glob filters restricting which file paths are edited.
pathstring
Root path to walk for files; used with `recursive`, `include_glob`, `exclude_glob`.
patternstring*required
Rust regex by default; set regex:false for a literal string.
recursiveboolean
Descend into subdirectories when `path` is set (default true).
regexboolean
Treat pattern as a regex (default true) or a literal string (false).
replacementstring*required
String to substitute for each match.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
resultsobject[]*required
Per-file replacement details.
replacementsinteger· uint64*requiredmin 0
total_replacementsinteger· uint64*requiredmin 0
Sum of replacements made across all files.
Stat a single path (jail-relative when fs.host_roots are set). Returns the entry's type, size, mode, and mtime. Errors return { code, message }; common: S211 not found, S215 jail/denylist.
pathstring*required
Jail-relative when fs.host_roots are set, else absolute.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
is_symlinkboolean*required
mtimeinteger· int64*required
sizeinteger· uint64*requiredmin 0
Write a file. Simplest form: { path, content: "text" } — `content` as a plain STRING is written inline (host target only), no streaming channel needed. For large/streamed payloads or a sandbox target, pass `content` as a ContentRef { channel_id, access_key, direction } from a write stream channel you opened through the engine's streaming layer (inline strings reject S210 on a sandbox target). To write several files at once, pass `files: [{ path, content, mode?, parents? }, ...]` instead of the single-file fields (host target, inline content) — the response then carries per-file results in `files`. `mode` is octal (default "0644"); `parents: true` creates missing parents. Errors return { code, message }; common: S210 bad mode/payload or inline-on-sandbox, S215 jail/denylist, S218 payload exceeds max_write_bytes, S216 channel/IO error.
contentany of
Single-file content: a plain string written inline (host target only), OR a ContentRef { channel_id, access_key, direction } for an open write stream channel. Omit when using `files`.
any of (2)
variant 1
any of (2)
variant 2
all of (1)
variant 1
access_keystring*required
Secret key that authorises access to this channel.
channel_idstring*required
Opaque identifier for the open stream channel.
directionall of
Direction of data flow: "read" (consume) or "write" (produce).
… expand 1 nestedcollapse
all of (1)
variant 1
valuestringenum: read, write
filesobject[]
Batch form: write several files in one call. When present, the single-file fields (`path`/`content`/`mode`/`parents`) must be omitted.
contentall of*required
Inline string (recommended) or a streaming ContentRef.
all of (1)
variant 1
any of (2)
variant 2
all of (1)
variant 1
access_keystring*required
Secret key that authorises access to this channel.
channel_idstring*required
Opaque identifier for the open stream channel.
directionall of
Direction of data flow: "read" (consume) or "write" (produce).
… expand 1 nestedcollapse
all of (1)
variant 1
valuestringenum: read, write
modestring
Octal permission string, e.g. "0644".
parentsboolean
Create missing parent directories.
pathstring*required
Jail-relative when fs.host_roots are set, else absolute.
modestring
Octal permission string for the single-file form, e.g. "0644". `Option` (not a defaulted `String`) so the batch-form check can tell "caller omitted mode" from "caller sent a mode" and reject the latter instead of silently dropping it. Defaults to "0644" in the single-file path. Omit when using `files` (each entry carries its own `mode`).
parentsboolean
Create missing parent directories (single-file form). `Option` for the same reason as `mode` — so a top-level `parents` sent alongside `files` is rejected, not ignored. Defaults to `false`. Omit when using `files`.
pathstring
Single-file form: the path to write. Jail-relative when fs.host_roots are set, else absolute. Omit when using `files`.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
variant 1
one of (2)
variant 1
kindstring*requiredenum: host
variant 2
kindstring*requiredenum: sandbox
sandbox_idstring· uuid*required
bytes_writteninteger· uint64*requiredmin 0
Bytes written: this file for a single write; the sum across `files` for a batch write.
filesobject[]
Per-file results for a batch (`files: [...]`) write; empty for a single-file write.
bytes_writteninteger· uint64*requiredmin 0
Bytes written to this file.
pathstring*required
Path of the written file.
pathstring*required
Path written for a single write; empty for a batch (see `files`).
Terminate a running background job by job_id (the UUID from shell::exec_bg). Errors return { code, message }; common: S211 no such job, S216 kill/signal delivery failure.
statusstring*requiredenum: running, finished, killed, failed
List background jobs (running + recently completed). Takes no arguments.
countinteger· uint*requiredmin 0
jobsobject[]*required
finished_at_msinteger· uint64min 0
started_at_msinteger· uint64*requiredmin 0
statusstring*requiredenum: running, finished, killed, failed
stderr_truncatedboolean*required
stdout_truncatedboolean*required
shell::on-config-change
functionInternal: reload the security policy + fs backend on configuration change.
idstring
Configuration id that changed (advisory; the handler re-fetches the value). Schema-only: kept to publish a typed request schema; the handler ignores it.
Fetch the full record (status, exit_code, timing) of a background job by job_id. Errors return { code, message }; common: S211 no such job.
jobobject*required
finished_at_msinteger· uint64min 0
started_at_msinteger· uint64*requiredmin 0
statusstring*requiredenum: running, finished, killed, failed
stderr_truncatedboolean*required
stdout_truncatedboolean*required
shell::workspace::list
functionConsole-only workspace picker control plane: list child directories under an existing host directory. Returns canonical paths and never returns files.
page_sizeinteger· uintmin 0
entriesobject[]*required
kindstring*requiredenum: dir
shell::workspace::roots
functionConsole-only workspace picker control plane: return canonical host directory anchors that an operator can browse before choosing a per-session working directory.
Console-only workspace picker control plane: validate that `path` is an existing host directory and return its canonical path.
