For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Use sandboxes with the gRPC API
Create a Sandbox, write a file, run a process, and stream its output from your own application by calling the kagent gRPC API.
An application that keeps its own agent loop, such as a chat app that runs the code that a model writes, calls the Sandbox API directly. This example uses grpcurl to show each request and reply. A real application generates a client from kagent’s protocol buffer definitions instead.
About the Sandbox API
The controller’s port 8083 serves both the gRPC API and the /mcp HTTP endpoint. The CLI and the MCP server reach the same Sandbox services.
| Service | Methods | What it covers |
|---|---|---|
kagent.api.v1.SandboxTemplateService | ListSandboxTemplates | Lists the templates in a namespace, with each template’s image and status. |
kagent.api.v1.SandboxService | CreateSandbox, GetSandbox, ListSandboxes, SuspendSandbox, ResumeSandbox, DeleteSandbox | Manages the lifecycle of a Sandbox. |
ateenv.v1alpha.ProcessService | StartProcess, GetProcess, StreamProcessOutput, SignalProcess, WriteProcessInput | Runs processes inside one Sandbox. |
ateenv.v1alpha.FileSystemService | WriteFile, ReadFile | Streams files into and out of one Sandbox, up to 64 MiB each. |
The process and file services are the Agent Substrate guest protocol, unchanged. A call to them selects the Sandbox with the kagent-sandbox-id metadata header. A call without the header fails with exactly one kagent-sandbox-id metadata value is required.
The lifecycle methods follow these rules.
- Retries: Each call makes one attempt. After a temporary error, repeat the same call.
CreateSandboxtakes a requiredrequest_id, from 1 to 128 characters. A retry with the samerequest_idand the same input returns the same Sandbox. A retry with the samerequest_idand different input fails withAlreadyExists, and the messagerequest_id was used for different input. - Conflicts: A call that conflicts with a lifecycle change that is still running fails with
Aborted. Retry it after the other call returns. - Reads:
GetSandboxandListSandboxesonly read state. They never advance pending work. - Process starts:
StartProcesshas no request ID. A start that times out might have started the process anyway, so check before you start it again.
Before you begin
Create a SandboxTemplate whose image includes Python, as described in Set up sandbox templates. The steps in this guide use the
pythontemplate in thekagentnamespace.Confirm that your installation sets
config.server.grpcReflection=true. Reflection lets grpcurl discover the controller’s methods without a local copy of kagent’s protocol buffer definitions.Install grpcurl and
jq, then check the setting.helm get values kagent -n kagent --all -o json \ | jq '.config.server.grpcReflection'Example output:
trueIf the value is
falseornull, save a values file and upgrade the existing release. The commands keep the installed chart version, and--reuse-valuespreserves your other installation settings.cat > grpc-values.yaml <<'EOF' config: server: grpcReflection: true EOF export KAGENT_CHART_VERSION=$(helm list -n kagent -o json \ | jq -er '.[] | select(.name == "kagent") | .chart | ltrimstr("kagent-")') helm upgrade kagent \ oci://ghcr.io/kagent-dev/kagent/helm/kagent \ --namespace kagent --version "$KAGENT_CHART_VERSION" \ --reuse-values -f grpc-values.yaml --waitPort-forward the controller’s API port in a separate terminal, and leave the command running.
kubectl port-forward -n kagent svc/kagent-controller 8083:8083Prepare authentication for your client. If your installation requires authentication, get an access token for your user and export it in the shell where you run the client commands.
export TOKEN="<access-token>"If your installation does not require authentication, leave
TOKENunset. For the available authentication modes, see Controller authentication modes.If you set
TOKEN, add-H "Authorization: Bearer $TOKEN"to everygrpcurlcommand in this guide.
Create a Sandbox
List the templates in the
kagentnamespace.grpcurl -plaintext -d '{"namespace":"kagent"}' \ localhost:8083 kagent.api.v1.SandboxTemplateService/ListSandboxTemplates \ | jq -c '.sandboxTemplates[] | {ref, workloadImage}'Example output:
{"ref":{"namespace":"kagent","name":"python"},"workloadImage":"docker.io/library/python:3.13-slim@sha256:e48f59cdba69a3cbd9ed2cf0f348d90d45a8d350d98134cf1070bc106ee9ed90"}List your existing Sandboxes. If you already have a ready Sandbox from the
pythontemplate that you want to use, save itsidin$SANDBOX_IDand skip the create step.grpcurl -plaintext -d '{}' \ localhost:8083 kagent.api.v1.SandboxService/ListSandboxes \ | jq -c '.sandboxes[]? | {id, name, sandboxTemplate, state, operation, expiresAt}'The command prints nothing when you have no Sandboxes. It lists only Sandboxes owned by the identity making the call.
If you need a new Sandbox, generate a request ID, create the Sandbox, and save its ID. Reuse
$REQUEST_IDonly to retry this same create request. For a new walkthrough, generate a new ID. The ID of an expired or deleted Sandbox producesFailedPrecondition, even if you change the display name.export REQUEST_ID="grpc-$(uuidgen)"set -o pipefail grpcurl -plaintext -d "$(jq -n --arg request_id "$REQUEST_ID" '{ sandbox_template: {namespace: "kagent", name: "python"}, request_id: $request_id, name: "grpc-demo", ttl: "900s" }')" \ localhost:8083 kagent.api.v1.SandboxService/CreateSandbox | tee sandbox.json export SANDBOX_ID=$(jq -er '.sandbox.id | select(length > 0)' sandbox.json)Field Description sandbox_templateRequired. The namespace and name of the template. request_idRequired. The key that makes the call safe to retry. Keep it until the call succeeds. Use a new key for a new Sandbox. nameOptional. A display name, up to 200 characters. ttlOptional. The lifetime, from 1sto86400s, and capped by the installation’s maximum. When you omit it, the installation’s default applies.Inspect the output from the previous step. Before you run anything, check that
stateisRUNTIME_STATE_READYandoperationisRUNTIME_OPERATION_NONE.Example create output:
{ "sandbox": { "id": "01a1f081-7f80-72f2-a10c-d726a3859090", "creator": "admin@kagent.dev", "sandboxTemplate": { "namespace": "kagent", "name": "python" }, "preparedRevision": "3445391091bcf759f7519e35aa0b5c7414bbe0a4a22ab91d30828828061d7caf", "state": "RUNTIME_STATE_READY", "operation": "RUNTIME_OPERATION_NONE", "name": "grpc-demo", "createdAt": "2026-11-18T21:13:01.056859Z", "updatedAt": "2026-11-18T21:13:01.120894792Z", "expiresAt": "2026-11-18T21:28:01.056859Z" } }If you reused an existing Sandbox or the new Sandbox is still being created, call
GetSandboxwith its ID to check its current state. Repeat until it is ready. If the create call failed, retry the create request with the same request ID;GetSandboxdoes not retry pending work.grpcurl -plaintext -d "{\"sandbox_id\":\"$SANDBOX_ID\"}" \ localhost:8083 kagent.api.v1.SandboxService/GetSandbox \ | jq '.sandbox | {id, state, operation}'Example output:
{ "id": "01a1f081-7f80-72f2-a10c-d726a3859090", "state": "RUNTIME_STATE_READY", "operation": "RUNTIME_OPERATION_NONE" }
Run a program against a file
Write an input file into the Sandbox. The
chunkfield takes the file content in base64, and a relativepathresolves against/data/workspace. Themodefield takes decimal Unix permission bits, such as420for0644.grpcurl -plaintext -H "kagent-sandbox-id: $SANDBOX_ID" \ -d "{\"path\":\"input.json\",\"mode\":420,\"chunk\":\"$(printf '[2,3,5]\n' | base64)\"}" \ localhost:8083 ateenv.v1alpha.FileSystemService/WriteFileExample output:
{ "bytesWritten": "8" }WriteFileis a client-streaming method, so an application can send a large file in several chunks. grpcurl sends one chunk per request message.Start a process, and save its ID. The
commandfield takes an argument list, and the process starts in/data/workspaceunless you setcwd. The call returns as soon as the process starts.grpcurl -plaintext -H "kagent-sandbox-id: $SANDBOX_ID" \ -d '{"command":["python3","-c","import json; v = json.load(open(\"input.json\")); print(json.dumps({\"count\": len(v), \"sum\": sum(v)}))"]}' \ localhost:8083 ateenv.v1alpha.ProcessService/StartProcess | tee process.json export PROCESS_ID=$(jq -r '.processId' process.json)Example output:
{ "processId": "proc-122be2a77eec355d88547dc9", "command": [ "python3", "-c", "import json; v = json.load(open(\"input.json\")); print(json.dumps({\"count\": len(v), \"sum\": sum(v)}))" ], "pid": 9, "state": "PROCESS_STATE_RUNNING", "startedAt": "2026-11-18T21:13:08.251668463Z" }Stream the process’s output until it exits. With
followset totrue, the stream stays open until the process exits, and its last message reports the exit. To continue a stream that dropped, pass thestdout_offsetandstderr_offsetof the bytes that you already read.grpcurl -plaintext -H "kagent-sandbox-id: $SANDBOX_ID" \ -d "{\"process_id\":\"$PROCESS_ID\",\"follow\":true}" \ localhost:8083 ateenv.v1alpha.ProcessService/StreamProcessOutput | tee process-output.jsonExample output:
{ "stdout": "eyJjb3VudCI6IDMsICJzdW0iOiAxMH0K" } { "exit": { "processId": "proc-122be2a77eec355d88547dc9", "command": [ "python3", "-c", "import json; v = json.load(open(\"input.json\")); print(json.dumps({\"count\": len(v), \"sum\": sum(v)}))" ], "pid": 9, "state": "PROCESS_STATE_EXITED", "startedAt": "2026-11-18T21:13:08.251668463Z", "finishedAt": "2026-11-18T21:13:08.324095549Z" } }The exit message has no
exitCodefield, because grpcurl omits a field that has its default value, and the default exit code is0. A process that fails reports its code, such as"exitCode": 4.Decode the base64-encoded
stdoutfrom the saved stream. Pass the encoded text through standard input, becausebase64does not decode a text argument. This command works on macOS and Linux and decodes each chunk separately.jq -r '.stdout // empty' process-output.json | while IFS= read -r chunk; do printf '%s' "$chunk" | base64 --decode doneExample output:
{"count": 3, "sum": 10}To check a process without streaming its output, call
GetProcess.grpcurl -plaintext -H "kagent-sandbox-id: $SANDBOX_ID" \ -d "{\"process_id\":\"$PROCESS_ID\"}" \ localhost:8083 ateenv.v1alpha.ProcessService/GetProcessExample output:
{ "processId": "proc-122be2a77eec355d88547dc9", "command": [ "python3", "-c", "import json; v = json.load(open(\"input.json\")); print(json.dumps({\"count\": len(v), \"sum\": sum(v)}))" ], "pid": 9, "state": "PROCESS_STATE_EXITED", "startedAt": "2026-11-18T21:13:08.251668463Z", "finishedAt": "2026-11-18T21:13:08.324095549Z" }Read a file back from the Sandbox.
ReadFilestreams the file in chunks, each in base64.grpcurl -plaintext -H "kagent-sandbox-id: $SANDBOX_ID" \ -d '{"path":"input.json"}' \ localhost:8083 ateenv.v1alpha.FileSystemService/ReadFileExample output:
{ "chunk": "WzIsMyw1XQo=" }
Delete the Sandbox
Delete the Sandbox when the application has what it needs. Deletion removes the Sandbox’s files and releases its compute immediately.
grpcurl -plaintext -d "{\"sandbox_id\":\"$SANDBOX_ID\"}" \
localhost:8083 kagent.api.v1.SandboxService/DeleteSandbox \
| jq -c '.sandbox | {state, operation}'Example output:
{"state":"RUNTIME_STATE_DELETED","operation":"RUNTIME_OPERATION_NONE"}A deleted Sandbox stays deleted. Replaying the original CreateSandbox request with the same request_id fails with FailedPrecondition, rather than creating a new Sandbox. To start over, use a new request_id.
Clean up
Remove the local response files after deleting the Sandbox. Also remove
grpc-values.yamlif you created it to enable reflection.rm -f sandbox.json process.json process-output.json grpc-values.yaml unset SANDBOX_ID PROCESS_ID REQUEST_ID KAGENT_CHART_VERSION TOKENStop the port-forward by pressing
Ctrl+Cin its terminal.