Shell & Sandbox

The Agent uses @downcity/shell for local command execution, sandboxed runners, shell session management, and interactive approval flows.

Install

Shell is a peer dependency of @downcity/agent. When you install the agent, you can add the shell package:

pnpm add @downcity/shell

Shell

The Shell class manages command execution and interactive approval feedback.

Minimal usage

import { Shell } from "@downcity/shell";
import { Agent } from "@downcity/agent";

const shell = new Shell({ autoApprove: false });

const agent = new Agent({
  id: "demo",
  path: process.cwd(),
  shell,
});

Constructor options

interface ShellOptions {
  autoApprove: boolean;       // require manual approval for shell commands
  allowedCommands?: string[]; // restrict to specific commands
  workdir?: string;           // working directory for execution
}

Methods

shell.approve(input) — Approve a pending shell action.

shell.deny(input) — Deny a pending shell action.

shell.dispose() — Release shell resources.

Sandbox

Sandboxing is configured through the project's downcity.json and resolved at runtime by the SDK. The sandbox backend is selected automatically based on the host platform:

• macos-seatbelt — macOS sandbox
• linux-bubblewrap — Linux sandbox
• unrestricted-host — No sandboxing

The SDK's internal sandbox runner handles shell subprocess creation, platform-specific backend invocation, and one-shot command execution. You do not normally need to interact with it directly.

ConfigResolver

SandboxConfigResolver loads sandbox configuration from the project environment.

SandboxPreflight runs pre-execution checks to validate the sandbox setup.

Approval

ShellApprovalRuntime manages the interactive approval loop — command execution requires a manual approve/deny step when autoApprove is false.

ShellTools

ShellTools and ShellToolSchemas provide the AI-ready tool definitions that the Agent uses to expose shell capabilities to the model. You do not normally need to use them directly — they are wired automatically when you pass shell to the Agent constructor.