Skip to content

Agent tools#

Connect a desktop AI tool to the MCP endpoint and it gains a working environment: a sandboxed shell in your project, with the project's credentials and connections already wired in.

The agent's reasoning stays where it is — on the laptop, in the cloud, wherever it runs. The work happens in the sandbox, under policy, on the audit trail. Nobody hands the agent a raw credential.

Running commands#

Tool Purpose
shell_exec Run one command and get stdout, stderr, and the exit code back.
shell_spawn Start a long-running process and get a process id.
shell_stdin Write to a spawned process's stdin.
shell_stdout Read buffered output from a spawned process.
shell_kill Signal a spawned process. Defaults to SIGTERM.

shell_exec takes an optional workdir and a timeout in milliseconds — 30 seconds by default, up to 20 minutes for builds and installs. Output is captured per stream with a byte limit, so a runaway command cannot flood the agent's context.

The spawn family exists for anything that outlives a single request: a dev server, a long test run, an interactive tool the agent drives turn by turn.

What is in the sandbox#

The shell sandbox image ships with aws, gh, kubectl, and webfetch already installed, wired to the project's connections. Additional tooling is installable at runtime through mise, and every connector a policy grants shows up as a CLI too.

That means an agent can run kubectl get pods against a registered cluster without a kubeconfig, and aws s3 ls against a registered account without an access key. The credentials are injected at the network boundary, outside the agent's reach.

Working with files#

Tool Purpose
shell_read_file Read a file, optionally from a line offset with a line limit.
shell_write_file Write a file.
shell_edit_file Replace exact text in a file, with optional replace-all.
shell_download_file Produce a download for a file in the workspace.

Paths are relative to the workspace root. These exist alongside shell_exec because they are cheaper and safer than shelling out to cat and sed for the same job, and because an edit that must match exactly is better expressed as an edit than as a script.

Delegating to a coding sub-agent#

shell_claude_code hands a whole task to a coding agent running inside the sandbox, rather than driving it command by command from outside.

Parameter Purpose
prompt The task.
mode plan analyses without changing anything; edit (the default) makes changes.
sessionId Resume a previous call's context.
maxTurns Turn ceiling, 100 by default and 200 at most.
systemPrompt Override the sub-agent's system prompt.
workdir Where it works.

The call returns a task id; shell_claude_code_status polls it for output.

The useful pattern is two calls: run plan first to explore and design, then pass the same sessionId with mode: edit to implement. The second call inherits every file read and the full plan, instead of rediscovering the codebase.

Reach for this over shell_exec whenever the work needs multiple steps, reasoning, or investigation. shell_exec is for one-off commands.

Which project#

Every tool takes an optional projectId. With access to exactly one project, it is inferred and you can leave it out. With access to several, set it — or connect to the project-scoped endpoint so the choice is made once, at configuration time.

The governance you get for free#

Nothing about this toolbox is best-effort:

  • Network is default-deny. The sandbox reaches only what policy allows, down to domain, method, and path.
  • Credentials are never readable. The agent sees placeholders; the egress proxy substitutes real values on the way out. See Credentials.
  • Every command and every tool call is audited — the command itself, the actor, the result, the duration. See Audit trail.
  • Model spend is capped by spending limits when the agent uses managed inference.