ide

(alias: shell)v0.5.4

Published 3mo agoUsed in 1 kitbash exec filesystem ide shell terminal

Install

bash

iii trigger compose::add worker=ide@0.5.4

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions17

shell::config-status

Function

Report 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.

Request

Empty object

Response

last_errorstring
Build error from the most recent rejected reload (why it was refused).
last_outcomeone ofrequired
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· uint64requiredmin 0
Cumulative count of rejected reloads since boot (never reset).

shell::exec

Function

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 allowed_env 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.

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.
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_root` is set (else absolute), canonicalized, and must resolve inside `host_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 `allowed_env`, 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 `allowed_env`, 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
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired
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::exec_bg

Function

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 allowed_env keys, 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.

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`].
cwdstring
Optional working directory for this job (host target only). Same jail confinement and rules as [`ExecRequest::cwd`]: canonicalized, must resolve inside `host_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 `allowed_env` 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
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired
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::chmod

Function

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.

Request

gidinteger· uint32min 0
Optional chown to this numeric gid.
modestringrequired
Octal permission string, e.g. "0755".
pathstringrequired
Jail-relative when fs.host_root is 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
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired
uidinteger· uint32min 0
Optional chown to this numeric uid.

Response

entries_changedinteger· uint64requiredmin 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.

shell::fs::grep

Function

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.

Request

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).
pathstringrequired
Jail-relative when fs.host_root is set, else absolute.
patternstringrequired
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
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired

Response

matchesobject[]required
All collected match locations up to `max_matches`.
- contentstringrequired
- lineinteger· uint64requiredmin 0
- pathstringrequired
truncatedbooleanrequired
True when the result was capped by `max_matches` or `max_line_bytes`.

shell::fs::ls

Function

List directory contents. `path` is relative to the configured fs jail root (fs.host_root) 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.

Request

pathstringrequired
Jail-relative when fs.host_root is set, else absolute.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
Variant 1
one of (2)
Variant 1
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired

Response

entriesobject[]required
Metadata for each entry in the directory.
- is_dirbooleanrequired
- is_symlinkbooleanrequired
- modestringrequired
- mtimeinteger· int64required
- namestringrequired
- sizeinteger· uint64requiredmin 0

shell::fs::mkdir

Function

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.

Request

modestring
Octal permission string, e.g. "0755".
parentsboolean
Create missing parent directories.
pathstringrequired
Jail-relative when fs.host_root is set, else absolute.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
Variant 1
one of (2)
Variant 1
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired

Response

already_existedboolean
True when the path already existed and `parents` was set. Host only; sandbox targets default this to false (not a signal there).
createdbooleanrequired
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.

shell::fs::mv

Function

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.

Request

dststringrequired
Destination path; jail-relative when fs.host_root is set, else absolute.
overwriteboolean
Replace an existing destination instead of returning an error.
srcstringrequired
Source path; jail-relative when fs.host_root is set, else absolute.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
Variant 1
one of (2)
Variant 1
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired

Response

dststring
Destination path. Empty for sandbox targets.
movedbooleanrequired
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.

shell::fs::read

Function

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.

Request

pathstringrequired
Jail-relative when fs.host_root is set, else absolute.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
Variant 1
one of (2)
Variant 1
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired

Response

contentall ofrequired
Channel reference for streaming the file content back to the caller.
all of (1)
Variant 1
access_keystringrequired
Secret key that authorises access to this channel.
channel_idstringrequired
Opaque identifier for the open stream channel.
directionall of
Direction of data flow: "read" (consume) or "write" (produce).
Show 1 nestedHide nested
all of (1)
Variant 1
valuestringenum read, write
modestringrequired
Octal permission string of the file, e.g. "0644".
mtimeinteger· int64required
Last-modified time as a Unix timestamp (seconds).
sizeinteger· uint64requiredmin 0
File size in bytes at the time of the read.

shell::fs::rm

Function

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.

Request

pathstringrequired
Jail-relative when fs.host_root is 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
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired

Response

pathstring
The path that was targeted. Empty for sandbox targets.
removedbooleanrequired
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.

shell::fs::sed

Function

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.

Request

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`.
patternstringrequired
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).
replacementstringrequired
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
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired

Response

resultsobject[]required
Per-file replacement details.
- errorstring
- pathstringrequired
- replacementsinteger· uint64requiredmin 0
- successbooleanrequired
total_replacementsinteger· uint64requiredmin 0
Sum of replacements made across all files.

shell::fs::stat

Function

Stat a single path (jail-relative when fs.host_root is set). Returns the entry's type, size, mode, and mtime. Errors return { code, message }; common: S211 not found, S215 jail/denylist.

Request

pathstringrequired
Jail-relative when fs.host_root is set, else absolute.
targetall of
host (default) or { kind: "sandbox", sandbox_id }.
all of (1)
Variant 1
one of (2)
Variant 1
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired

Response

is_dirbooleanrequired
is_symlinkbooleanrequired
modestringrequired
mtimeinteger· int64required
namestringrequired
sizeinteger· uint64requiredmin 0

shell::fs::write

Function

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.

Request

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 1
valuestring
Variant 2
all of (1)
Variant 1
access_keystringrequired
Secret key that authorises access to this channel.
channel_idstringrequired
Opaque identifier for the open stream channel.
directionall of
Direction of data flow: "read" (consume) or "write" (produce).
Show 1 nestedHide nested
all of (1)
Variant 1
valuestringenum read, write
Variant 2
valuenull
filesobject[]
Batch form: write several files in one call. When present, the single-file fields (`path`/`content`/`mode`/`parents`) must be omitted.
- contentall ofrequired
  Inline string (recommended) or a streaming ContentRef.
  all of (1)
  Variant 1
  any of (2)
  Variant 1
  valuestring
  Variant 2
  all of (1)
  Variant 1
  access_keystringrequired
  Secret key that authorises access to this channel.
  channel_idstringrequired
  Opaque identifier for the open stream channel.
  directionall of
  Direction of data flow: "read" (consume) or "write" (produce).
  Show 1 nestedHide nested
  all of (1)
  Variant 1
  valuestringenum read, write
- modestring
  Octal permission string, e.g. "0644".
- parentsboolean
  Create missing parent directories.
- pathstringrequired
  Jail-relative when fs.host_root is 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_root is 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
kindstringrequiredenum host
Variant 2
kindstringrequiredenum sandbox
sandbox_idstring· uuidrequired

Response

bytes_writteninteger· uint64requiredmin 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· uint64requiredmin 0
  Bytes written to this file.
- pathstringrequired
  Path of the written file.
pathstringrequired
Path written for a single write; empty for a batch (see `files`).

shell::kill

Function

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.

Request

job_idstringrequired

Response

job_idstringrequired
killedbooleanrequired
reasonstring
statusstringrequiredenum running, finished, killed, failed

shell::list

Function

List background jobs (running + recently completed). Takes no arguments.

Request

Empty object

Response

countinteger· uintrequiredmin 0
jobsobject[]required
- exit_codeinteger· int32
- finished_at_msinteger· uint64min 0
- idstringrequired
- started_at_msinteger· uint64requiredmin 0
- statusstringrequiredenum running, finished, killed, failed
- stderr_truncatedbooleanrequired
- stdout_truncatedbooleanrequired

shell::on-config-change

Function

Internal: reload the security policy + fs backend on configuration change.

Request

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.

Response

okbooleanrequired

shell::status

Function

Fetch the full record (status, exit_code, timing) of a background job by job_id. Errors return { code, message }; common: S211 no such job.

Request

job_idstringrequired

Response

jobobjectrequired
- argvstring[]required
- exit_codeinteger· int32
- finished_at_msinteger· uint64min 0
- idstringrequired
- started_at_msinteger· uint64requiredmin 0
- statusstringrequiredenum running, finished, killed, failed
- stderrstringrequired
- stderr_truncatedbooleanrequired
- stdoutstringrequired
- stdout_truncatedbooleanrequired

Triggers0

No triggers registered

Install

Functions17

Triggers0

Search the registry