Shell Built-In
Built-in Shell tools, persistent Workspace Sandbox, and host approval
Shell is a built-in Workspace capability from @downcity/city, not a Power. Shell owns its SandboxProvider, the persistent Sandbox created for its Workspace, and all Shell Sessions created inside it. City does not know which execution backend the Workspace uses.
import { Agent } from "@downcity/agent";
import { City, Shell, Workspace } from "@downcity/city";
import { MicrosandboxProvider } from "@downcity/sandbox-microsandbox";
const workspace = new Workspace({
id: "project",
path: "/path/to/project",
shell: new Shell({
sandbox_provider: new MicrosandboxProvider(),
}),
});
const city = new City({
workspaces: [workspace],
});
const agent = new Agent({ id: "repo-helper" });
city.agents.add(agent);For a one-shot command, use shell({ action: "exec", args: { cmd: "pwd", max_output_tokens: 2000 } }). The optional max_output_tokens sets an approximate output token budget; max_output_chars is not a valid argument. Call shell() to inspect action schemas when uncertain. Unknown fields are rejected before execution, so correct the arguments and retry; the command has not run.
Use session_start for long-running or interactive commands, session_send for input, session_read for output, session_list to list sessions, and session_stop to end a process. Set auto_notify_on_exit: true to report completion automatically:
shell({
action: "session_start",
args: { cmd: "pnpm build", auto_notify_on_exit: true }
})With notifications enabled, success, failure, or an explicit stop returns completion information to the original Session. Each completion is handled once. A valid original execution processes it at execution checkpoints. Once that execution stops, closes, or is replaced, results remain saved without a late notification waking it again. Notifications do not guarantee forced interruption of model requests or synchronous tools. Set auto_notify_on_exit: false for an independent long-lived service so the Agent need not keep waiting. Restart recovery only delivers already saved completion results. Original processes that cannot be taken over are reported as interrupted or unknown, without automatically rerunning commands.
Shell commands default to target: "sandbox". Paths depend on the provider: Microsandbox mounts the project at /workspace; NativeSandboxProvider keeps the real host project path. Use target: "host" with a clear reason when host execution is required; the request must pass approval.
NativeSandboxProvider uses Seatbelt on macOS and Bubblewrap on Linux. It permits host file reads except for protected paths and permits writes to the Workspace, runtime and platform temporary directories. A read-only grant blocks writes even inside a writable root. Protected paths block both reads and writes; on Linux their content is hidden behind empty mounts. This is not an isolated HOME or a filesystem read allowlist. Network access is configured separately and defaults to allowed.
Before native command launch, credential-like environment variables (tokens, API keys, passwords, secrets and credential paths) and SSH agent variables are removed. Host code can grant specific names through new NativeSandboxProvider({ allowed_credential_env: ["NPM_TOKEN"] }); names match exactly. Downcity internal authentication tokens are always removed. PATH, HOME and non-credential build settings remain available. This filters inherited variables only: login scripts and readable host files may still supply credentials, and unrecognized variable names are not detected.
Host code can explicitly authorize an SSH agent without exposing private key files:
const sandbox_provider = new NativeSandboxProvider({
ssh: {
socket_path: "/absolute/path/to/agent.sock",
known_hosts_path: "/absolute/path/to/dedicated_known_hosts",
},
});The paths must exist as a Unix socket and regular file, and network must be allow. Maintain a dedicated known_hosts file after verifying remote fingerprints; unknown hosts are not trusted automatically. The host-authorized socket replaces command-provided SSH_AUTH_SOCK. Without SSH authorization, this variable is removed even if included in the generic credential allowlist. Git receives a default SSH command that ignores user configuration, does not load private keys, disables agent forwarding and strictly verifies hosts. Direct ssh calls need their own corresponding options; the Git default is not an enforced policy for arbitrary commands.
Authorization grants signing use of the agent identities, not repository-scoped access. The standard agent protocol does not export private keys. CLI/Desktop does not authorize SSH automatically. Desktop Workspace settings include an SSH identity section for an explicit socket and verified known_hosts records, with a native confirmation before applying. Authorization persists per Workspace; socket identity changes require authorization again. Changes interrupt tasks and rebuild the Workspace runtime. Reconstruction errors are reported and leave runtime access blocked until a retry. CLI has no authorization management command yet, but Workspace creation validates and uses saved records. Exact authorized endpoints can reopen within protected directories. sandbox.get reports the known_hosts exception through allowed_read_paths; path explanations allow that exact file while keeping sibling files protected. A socket grants connection capability, not file-read access, and the path explanation API does not judge socket connections.
Use context.sandbox.get to inspect the effective boundary. writable_roots lists broad write grants; denied_write_paths takes precedence and includes read-only and protected subtrees. denied_read_paths lists protected content. context.sandbox.explain_path checks write exclusions before writable roots. Native policies resolve existing path aliases when created; path explanations remain lexical.
Native provider self-checks validate allowed writes, outside writes, read-only grants, protected content and child-process inheritance using disposable probe files. A local TCP service verifies connectivity under the allow policy and isolation under the deny policy without internet access. This checks TCP to host loopback, not every protocol. Probe timeouts, launch errors and self-check exceptions are failures. Errors report the exit code, termination signal or timeout, with a bounded stderr excerpt; a crashed process never counts as successful network isolation. Electron hosts enable Node mode only for Node probe children, so the desktop parent and ordinary Shell commands do not need ELECTRON_RUN_AS_NODE. A network_allow_probe_failed error means the local probe failed: use the attached cause to investigate the runtime or loopback connection rather than assuming an internet outage. Linux execution also fails when a missing restricted path beneath a writable root cannot be safely enforced.
Chat Sessions in one Workspace share its sandbox resources. Native execution uses the host toolchain and HOME; it does not provide separate machines or temporary directories per Workspace. A shell_id identifies a Shell Session and is never interchangeable with a Chat session_id.
Before the first sandbox command, Shell waits for SandboxProvider.check(). Concurrent commands share one check. A failed or throwing check blocks sandbox launches; it never triggers automatic host execution. The result remains cached until a successful explicit reset_sandbox(), after which the next command checks again. Providers without reset require a new Shell/Workspace to retry. Reset rejects new commands while in progress; a failed reset keeps sandbox execution blocked until reset succeeds. Disposal rejects new work and commands waiting for readiness. Host execution follows its separate approval flow.
Closing City or Workspace preserves persistent files. Native execution has no persistent VM to stop; Shell owns command lifecycle management.
See Shell and Sandbox for lifecycle, environment, and approval details.