iii / worker
$worker

shell

v0.3.2

Unix shell + filesystem worker — exec with allowlist/denylist/timeout/output caps and background jobs; fs::ls|stat|mkdir|rm|chmod|mv|grep|sed|read|write with host jail, denylist, size caps, and sandbox-target forwarding

  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64

functions

15

shell::fs::mkdir

function

Create a directory on host or sandbox

request
valueunknown
response
  • createdbooleanrequired

shell::fs::rm

function

Remove a path on host or sandbox

request
valueunknown
response
  • removedbooleanrequired

shell::fs::mv

function

Move/rename a path on host or sandbox

request
valueunknown
response
  • movedbooleanrequired

shell::fs::ls

function

List directory contents on host or sandbox

request
valueunknown
response
  • entriesunknown[]required

shell::fs::grep

function

Recursive regex search on host or sandbox

request
valueunknown
response
  • matchesunknown[]required
  • truncatedbooleanrequired

shell::status

function

Get status of a background job

request
  • job_idstringrequired
response
  • jobunknownrequired

shell::exec

function

Run an allowlisted command in the foreground and return its full output. Payload: { command: string (program name), args?: string[], timeout_ms?: number, target?: { kind: 'host'|'sandbox', sandbox_id?: string } }. Returns { stdout, stderr, exit_code, duration_ms, timed_out, stdout_truncated, stderr_truncated }. Do NOT pass argv as an array in 'command' — split program and arguments across the two fields.

request
  • 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`.

  • commandstringrequired

    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.

  • 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
    valueunknown
  • 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).

response
  • duration_msinteger· uint64requiredmin 0
  • exit_codeinteger· int32
  • stderrstringrequired
  • stderr_truncatedbooleanrequired
  • stdoutstringrequired
  • stdout_truncatedbooleanrequired
  • timed_outbooleanrequired

shell::list

function

List all background jobs

request
valueunknown
response
  • countinteger· uintrequiredmin 0
  • jobsunknown[]required

shell::kill

function

Kill a running background job

request
  • job_idstringrequired
response
  • job_idstringrequired
  • killedbooleanrequired
  • reasonstring
  • statusunknownrequired

shell::fs::write

function

Stream a file to a host path or sandbox via StreamChannelRef

request
valueunknown
response
  • bytes_writteninteger· uint64requiredmin 0
  • pathstringrequired

shell::fs::sed

function

Find-and-replace on host or sandbox

request
valueunknown
response
  • resultsunknown[]required
  • total_replacementsinteger· uint64requiredmin 0

shell::exec_bg

function

Spawn an allowlisted command as a background job. Same payload shape as shell::exec; returns { job_id, argv } immediately. Poll with shell::status, terminate with shell::kill, list with shell::list. Do NOT pass argv as an array in 'command' — use 'command' (string) + 'args' (string[]).

request
  • 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`.

  • commandstringrequired

    Program name. See [`ExecRequest::command`].

  • targetall of

    Where to run. See [`ExecRequest::target`].

    all of (1)
    variant 1
    valueunknown
  • timeout_msinteger· uint64min 0

    Per-call timeout. Host-targeted background jobs IGNORE `timeout_ms`; sandbox-targeted ones forward it through `cfg.resolve_timeout`.

response
  • argvstring[]required
  • job_idstringrequired

shell::fs::stat

function

Stat a path on host or sandbox

request
valueunknown
response
  • is_dirbooleanrequired
  • is_symlinkbooleanrequired
  • modestringrequired
  • mtimeinteger· int64required
  • namestringrequired
  • sizeinteger· uint64requiredmin 0

shell::fs::read

function

Stream a file from a host path or sandbox via StreamChannelRef

request
valueunknown
response
  • contentunknownrequired
  • modestringrequired
  • mtimeinteger· int64required
  • sizeinteger· uint64requiredmin 0

shell::fs::chmod

function

Change permissions on host or sandbox

request
valueunknown
response
  • updatedinteger· uint64requiredmin 0

triggers

0
no triggers registered