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