Already using the Anthropic or OpenAI SDK? Ship your agent to production in one call.

See the quickstart

Jettson Shell

Run shell commands inside the agent's isolated workspace.

Every agent has a real Linux shell on its computer — Python, Node, curl, git, and the rest of the standard toolchain. Hard timeouts, output caps, and a destructive-pattern blocklist apply inside /workspace.

jettson_shell_run

| Field | Type | Description | | --- | --- | --- | | command (required) | string | The shell command to run. Executed via /bin/sh -c, so pipes/redirects/&& chains are fine. | | timeout_seconds | number | Per-call timeout (default 30). Capped server-side at 60 — values higher are clamped. |

Returns:

json
{
  "stdout": "Hello world\n",
  "stderr": "",
  "exit_code": 0,
  "truncated": false,
  "timed_out": false
}

truncated is set if combined stdout+stderr exceeded 10 MB (rare for normal workflows). timed_out is set if the timeout fired before exit.

Working directory

Commands always start in /workspace. You can cd to a subdir within the command, but each jettson_shell_run call starts fresh in /workspace — there's no shell state between calls.

What's installed by default

  • Python 3 (python3, pip3)
  • Node.js + npm
  • curl, wget, git, jq
  • Standard coreutils

To install something else:

bash
pip3 install some-package
# or
npm install --no-save some-pkg

Installs are scoped to the agent's workspace — they don't persist across runs.

What's blocked

The shell refuses commands matching obviously-destructive patterns:

  • rm -rf / (root) — won't execute
  • Fork bombs (:(){:|:&};: and variants) — won't execute
  • mkfs.*, dd if=… of=/dev/* — won't execute
  • shutdown, reboot, halt, poweroff — won't execute

These return:

json
{
  "error": "Jettson Shell rejected the command: command matches a blocked pattern (destructive or escape attempt)."
}

The list is conservative — false-negatives over false-positives. We won't block your npm test because someone else's prompt was hostile.

Hard limits

| | | | --- | --- | | Wall-clock per call | 60 seconds max | | Combined output | 10 MB (truncated above this) | | Working directory | /workspace only |

Example

A small data-processing run:

text
jettson_shell_run({
  command: "curl -sS https://raw.githubusercontent.com/.../data.csv | head -100 > data.csv && wc -l data.csv"
})

Returns the line count plus the file lands in /workspace/data.csv for subsequent jettson_files_read / jettson_shell_run calls.

Failure modes

| Situation | Field on result | | --- | --- | | Command exited non-zero | exit_code !== 0, stderr populated | | Wall-clock timeout | timed_out: true, exit_code: 124 | | Output > 10 MB | truncated: true, output truncated with a marker | | Blocked pattern | Top-level error, no exit code |

Security notes

Shell runs in the agent's isolated container — destroying the container at run end cleans up everything the command did. There's no shared filesystem with other agents or your laptop. That said:

  • Don't pass user-controlled strings into the command unsanitized inside your task prompt. The Mind is reasonable about quoting, but the safest pattern is to write user input to a file with jettson_files_write first and read it from there.
  • Don't rely on the shell for permanence — /workspace is gone at the end of the run. Use Jettson Memory for cross-run state.

Related