For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Run commands with the CLI
Create a Sandbox, run commands, move files in and out, and suspend, resume, and delete it with the kagent CLI.
The kagent sandbox commands give a person or a script a scratch environment on demand. In this guide, you create a Sandbox, run a script against a file that you upload, download the result, and then walk the Sandbox through its lifecycle.
Before you begin
Download the latest kagent CLI.
curl -sL https://kagent.dev/install | bashTo install a particular version instead, run
curl -sL https://kagent.dev/install | bash -s -- --version v1.0.0.Create a SandboxTemplate whose image includes Python, as described in Set up sandbox templates. The steps in this guide use the
pythontemplate in thekagentnamespace.To read the Sandbox ID from the CLI’s JSON output, install
jq.
Create a Sandbox
List the templates that you can create a Sandbox from. The list includes only the templates in the namespace that
--namespaceselects, which defaults tokagent.kagent sandbox templatesExample output:
NAMESPACE NAME IMAGE kagent python docker.io/library/python:3.13-slim@sha256:e48f59cdba69a3cbd9ed2cf0f348d90d45a8d350d98134cf1070bc106ee9ed90Generate a request ID for this walkthrough, then create a Sandbox and save its ID. To retry the create command, reuse
$REQUEST_ID. To start a new walkthrough after deleting or expiring the Sandbox, generate a new request ID.export REQUEST_ID="cli-$(uuidgen)" export SANDBOX_ID=$(kagent sandbox create python \ --request-id "$REQUEST_ID" --name my-first-sandbox --ttl 30m \ -o json | jq -er '.id | select(length > 0)') echo $SANDBOX_IDFlag Description --request-idRequired. A key that makes the call safe to retry. To retry a failed create, repeat the command with the same request ID and the same flags. A new request ID creates a second Sandbox. --nameOptional. A display name. --ttlOptional. The Sandbox’s lifetime, such as 30m. When you omit it, the installation’s default applies, which is one hour unless an operator changes it. The installation also caps the lifetime, at 24 hours by default.Check the Sandbox. A Sandbox is ready for commands when
STATEisRUNTIME_STATE_READYandOPERATIONisRUNTIME_OPERATION_NONE. A template that is already prepared usually gives a ready Sandbox as soon as the create command returns.kagent sandbox get $SANDBOX_IDExample output:
ID TEMPLATE STATE OPERATION EXPIRES FAILURE 01a1f073-a9ad-77b8-88fc-8f63b3381122 kagent/python RUNTIME_STATE_READY RUNTIME_OPERATION_NONE 2026-11-18T21:27:54ZTo see every Sandbox that you own, run
kagent sandbox list. The list does not include other users’ Sandboxes.
Run commands and move files
Run a command. The CLI prints the process ID when the process starts, streams the output, and reports the exit code when the process finishes.
kagent sandbox exec $SANDBOX_ID -- python --versionExample output:
Process proc-8287f5220c1764358c4134bd in sandbox 01a1f073-a9ad-77b8-88fc-8f63b3381122: started (stdout offset 0, stderr offset 0) Python 3.13.18 Process proc-8287f5220c1764358c4134bd: PROCESS_STATE_EXITED, exit_code=0The
--separator is required before the command. The command runs without a shell, so to use pipes, redirects, or variables, run a shell explicitly, such as-- sh -c 'echo $LANG'. Theexeccommand also takes the following options.Flag Description --cwdThe working directory. Defaults to /data/workspace.--envAn environment variable for this process, as KEY=VALUE. Repeat the flag to set more than one.--waitWhether to wait for the process to finish. Defaults to true. With--wait=false, the command returns as soon as the process starts.--timeoutHow long the CLI waits, such as 30s. Defaults to5m. A timeout stops the CLI from waiting, but the process keeps running in the Sandbox.When the process exits with a nonzero code,
kagent sandbox execexits with the same code, so a script can check the result.Create a script and an input file on your machine.
cat > summarize.py <<'EOF' import json values = json.load(open("input.json")) json.dump({"count": len(values), "sum": sum(values)}, open("summary.json", "w")) print("wrote summary.json") EOF printf '[2,3,5]\n' > input.jsonUpload both files. A relative destination path resolves against
/data/workspace. An upload replaces a file that already exists.kagent sandbox upload $SANDBOX_ID ./summarize.py summarize.py kagent sandbox upload $SANDBOX_ID ./input.json input.jsonExample output:
Wrote 160 bytes to summarize.py Wrote 8 bytes to input.jsonRun the script.
kagent sandbox exec $SANDBOX_ID -- python summarize.pyDownload the result. The CLI replaces the local file only after the download succeeds.
kagent sandbox download $SANDBOX_ID summary.json ./summary.json cat summary.jsonExample output:
./summary.json {"count": 3, "sum": 10}
The CLI streams each file, up to 64 MiB. Only regular files can be transferred. To move a directory, archive it first, such as with tar, and then upload or download the archive.
Work with long-running processes
A process keeps running in the Sandbox when the CLI stops waiting for it, for example after a timeout or a lost connection. Keep the process ID so that you can reconnect.
Start a process without waiting, and save its process ID. The
-o jsonoutput prints one JSON record per line, and the first record reports the process ID.export PROCESS_ID=$(kagent sandbox exec $SANDBOX_ID --wait=false -o json -- \ sh -c 'for i in 1 2 3 4 5 6; do echo tick $i; sleep 2; done' \ | jq -r 'select(.event=="started").process_id')Check the process without waiting for it.
kagent sandbox process $SANDBOX_ID $PROCESS_IDExample output:
proc-d7eadee9cf78f00bf537e195 PROCESS_STATE_RUNNINGReconnect to the process, and wait for it to finish. The
waitcommand prints the output from the start, then the exit code. To skip output that you already read, pass the offsets that an interrupted command reported, with--stdout-offsetand--stderr-offset.kagent sandbox wait $SANDBOX_ID $PROCESS_IDExample output:
tick 1 tick 2 tick 3 tick 4 tick 5 tick 6 Process proc-d7eadee9cf78f00bf537e195: PROCESS_STATE_EXITED, exit_code=0Start a new process to try stopping it. The previous process has already exited, so killing it would fail. This process sleeps for 10 minutes, leaving time to run the next command.
export PROCESS_ID=$(kagent sandbox exec $SANDBOX_ID --wait=false -o json -- \ sh -c 'echo running; sleep 600' \ | jq -r 'select(.event=="started").process_id')Stop the new process with
kagent sandbox kill, then read its exit code. The command sendsSIGKILLand returns as soon as the guest delivers the signal, so its output can still reportPROCESS_STATE_RUNNING.kagent sandbox kill $SANDBOX_ID $PROCESS_ID kagent sandbox wait $SANDBOX_ID $PROCESS_IDExample output:
proc-65dc86558ccbc67f8f4c5204 PROCESS_STATE_RUNNING running Process proc-65dc86558ccbc67f8f4c5204: PROCESS_STATE_EXITED, exit_code=137 Error: sandbox process exited with code 137The nonzero exit code is expected for a killed process.
Read JSON output in a script
With -o json, the exec and wait commands print one JSON record per line, so a script can follow a process without parsing the table output.
kagent sandbox exec $SANDBOX_ID -o json -- sh -c 'echo out; echo err >&2; exit 3'Example output:
{"event":"started","sandbox_id":"01a1f073-a9ad-77b8-88fc-8f63b3381122","process_id":"proc-7d73878f680b7009754a2f40","stdout_offset":0,"stderr_offset":0}
{"event":"output","sandbox_id":"01a1f073-a9ad-77b8-88fc-8f63b3381122","process_id":"proc-7d73878f680b7009754a2f40","source":"stdout","data":"b3V0Cg==","stdout_offset":4,"stderr_offset":0}
{"event":"output","sandbox_id":"01a1f073-a9ad-77b8-88fc-8f63b3381122","process_id":"proc-7d73878f680b7009754a2f40","source":"stderr","data":"ZXJyCg==","stdout_offset":4,"stderr_offset":4}
{"event":"finished","sandbox_id":"01a1f073-a9ad-77b8-88fc-8f63b3381122","process_id":"proc-7d73878f680b7009754a2f40","state":"PROCESS_STATE_EXITED","exit_code":3,"stdout_offset":4,"stderr_offset":4}| Event | When it is printed | Fields beyond the IDs and offsets |
|---|---|---|
started | Once, when the process starts | None |
output | For each chunk of output | source, which is stdout or stderr, and data, which is the chunk in base64 |
finished | Once, when the process exits | state and exit_code |
interrupted | Once, when the CLI stops waiting before the process exits, such as after a timeout | None. Pass the offsets to kagent sandbox wait to continue. |
Other kagent sandbox commands print a single JSON object with -o json, with field names in camel case, such as expiresAt.
Suspend and resume a Sandbox
Suspending a Sandbox releases its compute while keeping its files. Resuming it brings the files back on whichever Worker has room.
Important
Suspending a Sandbox interrupts whatever it is doing. kagent sandbox suspend does not wait for any process, output stream, or file transfer, so a command can be cut off partway through and a file can be left partly written. Resuming restores the files under /data, but not the running processes or their IDs. Suspend a Sandbox only when you can repeat what it was running.
Suspend the Sandbox.
kagent sandbox suspend $SANDBOX_IDExample output:
ID TEMPLATE STATE OPERATION EXPIRES FAILURE 01a1f073-a9ad-77b8-88fc-8f63b3381122 kagent/python RUNTIME_STATE_SUSPENDED RUNTIME_OPERATION_NONE 2026-11-18T21:27:54ZTry listing the workspace while the Sandbox is suspended. kagent does not resume a Sandbox automatically, so the command fails.
kagent sandbox exec $SANDBOX_ID -- ls /data/workspaceExample output:
Error: start process in sandbox 01a1f073-a9ad-77b8-88fc-8f63b3381122: command may have started; do not blindly retry: rpc error: code = FailedPrecondition desc = Sandbox is not ready or has expiredResume the Sandbox. The expiration time stays the same, because resuming does not extend the lifetime.
kagent sandbox resume $SANDBOX_IDRepeat the workspace command. It now succeeds and confirms that the files that you created are still in
/data/workspace.kagent sandbox exec $SANDBOX_ID -- ls /data/workspaceExample output:
Process proc-c1c4db1babc16359c2e26b2e in sandbox 01a1f073-a9ad-77b8-88fc-8f63b3381122: started (stdout offset 0, stderr offset 0) input.json summarize.py summary.json Process proc-c1c4db1babc16359c2e26b2e: PROCESS_STATE_EXITED, exit_code=0Files that a command wrote outside
/data, such as in/tmp, are gone, and a process ID from before the suspension returnsprocess ... not found.
Delete the Sandbox
If you do not delete a Sandbox, kagent deletes it when it expires.
Download any files that you want to keep, such as the result from this guide. Deletion removes the Sandbox’s files.
kagent sandbox download $SANDBOX_ID summary.json ./summary.jsonDelete the Sandbox to release its compute and storage immediately.
kagent sandbox delete $SANDBOX_ID