Skip to main content
system:compute is the package the agent lives in. Eleven tools over one idea: every one of them takes a target that says which machine it runs on, and the default target is the agent’s own.
The three targets: compute_target acquires and lists them:
Everything below runs on any of the three unless it says otherwise.

​
Running a command

compute_exec has no fast lane and no slow lane. You run the command; if it outlives the wait, it is not killed — the reply is
and the finished result is delivered to the agent later as a wake-up. So a build, a full test suite and an hour-long script are all just commands, and polling for one is wasted work: the answer arrives on its own.
timeout_seconds is a kill deadline for ssh and local targets only — those have no way to deliver a late result. On the sandbox nothing is killed for being slow.

​
Keeping a shell

compute_exec forgets everything between calls. compute_shell is a real PTY that does not: cd, exported variables and background jobs survive, and a program started in the session receives later writes on its stdin.
The ops are open, write, read, peek, kill and list. read polls for new output without writing, peek returns the transcript without consuming it. Two things follow from it being a terminal rather than a pipe. The output carries the terminal’s escape codes and prompt, so strip them or grep them rather than comparing strings. And control characters are signals: chars="\x03" interrupts the running program instead of typing three characters at it. Use it for a REPL, an ssh session, an interactive installer, anything where the next command depends on the state the last one left. Background a long-running process with a trailing & so the session stays usable, then reach for compute_preview.

​
Files

Four tools, and the choice between them is not stylistic.
​
Read a file, optionally a range of it. max_kb caps at 32.
​
Create or overwrite one file, parent directories included. One file per call.
​
Exact string replacement in place — the default for changing an existing file.
​
ripgrep. output_mode="files_with_matches" is the cheapest and the default.
compute_edit is worth understanding before the first failure. old_string must match the file including whitespace, and it must identify exactly one place:
There is a matching cascade that forgives minor drift — trimmed lines, block anchors, normalized indentation — but exact text copied out of a read is the reliable path. The result includes a unified diff of what changed, and edits to the same file are serialized, so parallel edits to different files are safe.

​
Seeing things

compute_view hands the agent an image — a screenshot, a chart, a photograph — as an image rather than as bytes:
Called from code you get the caption, "shot.png (image/png, 643716 bytes)", and the picture itself reaches the model. png, jpeg, gif and webp, up to about 5 MB. For text use compute_read_file.

​
The desktop

compute_computer drives a real X11 desktop with Chromium on it: open_url, screenshot, click, type, key, hotkey, scroll, drag. Sandbox only.
It is the right browser for signing in and signing up, and the wrong one for everything else. Driving a browser says why.

​
Handing something over

Two tools, and the difference is whether you are sharing a file or a server.
compute_download pulls one file off the target and returns a signed URL, up to 100 MiB. compute_preview exposes a port the sandbox is already listening on — a dev server, an API, or python3 -m http.server 8080 --directory ~/site & when what you want is to show somebody a page. A splox.app link renders inline in the chat, so the reader sees the page without leaving the conversation.
compute_preview is sandbox-only; ssh and local targets are refused. Both URLs are signed and expire — an hour by default, expires_in_seconds up to 86400 — so they are for showing a person, not for building an integration on.

​
Which tool for which job