Code execution & sandbox

When the agent runs a shell command, a Python cell, or a build, it does so inside a managed sandbox, not on the host serving the API. This page documents where that execution happens, how isolated it is, and the exact tools the agent uses, with their parameters and return shapes.

Isolation

The execution environment is chosen and operated by the platform; it is not set in the API request. You write the same tool calls either way, and isolation is an operational guarantee, not a parameter.

• Filesystem jail: file access is confined to the session workspace; path traversal outside the root is rejected before any I/O.
• Network closed by default: only a restricted set of platform hosts is reachable. Keyed third-party APIs are called through connectors, not from the sandbox.
• No connector secrets inside: connector secrets (API keys, tokens, passwords) never enter the sandbox environment: code reaches a connector through the host, which holds its credentials. os.environ carries only a connection's non-secret identifiers, the user's own variables and the variables an Environment names.
• Per-session filesystem: each session gets its own workspace. Every sandbox_bash call starts a fresh shell: cd and environment variables do not reach the next call, so keep intermediate state in files.

Files & persistence

work and output survive a sandbox restart between turns. The repl_execute namespace is snapshotted and restored too; when a restore fails, the agent sees a [SYSTEM: …] note or a NameError. Files move between the cloud and the user's computer via copy_from_computer and copy_to_computer (up to 100 megabytes per file, the file is addressed by artifact_id).

On the user's computer, analyze accepts paths in the chat folder or its working directories. For a file outside those directories, copy_from_computer checks permission to import that exact file. A file can come from any local drive (D:\, C:\Work); on «Ask before changes», a file outside the home folder is copied only after you allow that path. Credential and password stores and network shares (\\server\share) are never copied; map a share to a drive letter instead. copy_to_computer writes only into the chat folder and the home folder; to write elsewhere, bind that folder to the chat. The agent passes the returned artifact_id to analyze.

Tools

A turn runs either in the cloud sandbox (sandbox_bash) or on the user's computer through the desktop app (exec_command + write_stdin). The wrong shell answers with a refusal that names the right one. edit_file edits files wherever the turn runs.

sandbox_bash: run shell / Python

One-shot, non-interactive command in the cloud sandbox. Returns captured streams plus files from output.

Returns:

repl_execute: persistent Python REPL

A Jupyter-like Python session: one process per conversation, the namespace outlives the calls, and a failed cell does not roll back what already ran. Built-in helpers (peek, grep, chunk_indices, llm_query, save_artifact, FINAL and more) help work over large data without re-loading it each step.

The call returns an execution receipt and captured output. Computed objects stay under their Python names: read_stdout(ref) reads the output, while read_first(ref) selects the receipt record. To inspect a saved object, print it in the next cell, for example print(rows). The computation does not need to run again.

A cell that outlasts the initial window keeps running while the agent's turn pauses. The runtime collects the receipt before the turn continues. The cell retains its own execution deadline. Reaching it resets the kernel. Variables from completed cells are restored from a snapshot, while name changes from the interrupted cell are lost. Writes already applied to external services remain. Reconcile their state and saved progress before retrying.

A syntax error returns its line and position for repair; by itself, it neither ends the turn nor raises the token limit. The provider response determines whether a tool call was truncated: that call is withheld from execution and retried with a larger output budget.

exec_command: live shell session

Runs a command in a shell session on the user's computer through the desktop app, in the chat's folder, using pipes. Commands that finish during the initial window return stdout and exit_code directly. A finite command that outlasts the window pauses the turn. On wake, the runtime checks the same session and reads from the saved output position. If the connection drops, the result stays unknown until a read succeeds. For servers, REPLs and watchers left running, the agent can use write_stdin with their session_id.

The agent launches Claude Code and supported ACP agents in managed mode, with a direct command, cli_agent, and task. The runtime delivers the task and handles permission requests. Standalone diagnostics such as claude auth status --text use an ordinary shell command.

Returns session_id, pid, stdout, status (running / exited / killed), exit_code, alive and next_since: pass it as since to write_stdin to continue reading from the same spot. dropped_bytes > 0 means the start of the output was evicted from the buffer and is lost.

write_stdin: drive a live session

Reads the output and status of an exec_command session, including a retained result after exit. A running session also accepts input. Append \n to submit a line.

edit_file and apply_patch: surgical file edits

edit_file creates, overwrites, edits, deletes and renames one file wherever the turn runs (the cloud or the user's computer); op selects the operation. apply_patch takes a V4A patch across several files and edits: the patch headers name the files, and it lands whole or not at all. Whole-line matching tolerates edge whitespace and typographic punctuation; missing or ambiguous text returns diagnostics so the agent can revise the edit.

What you see through the API

Tool calls arrive on the OpenAI-compatible endpoint as named samreshuuu.tool events (tool_started / tool_completed) when a streaming request sets tool_events: true (Streaming). repl_execute is also exposed to external clients through the MCP server.