Tool server

Description and operation

General

Every workspace runs a tool server. An agent calls its tools with the tool call of its session, and each call takes workspace, the id of the workspace. The id starts with ws-. The agent never sends HTTP itself. The Claude Code plugin, the MCP server and the harness forward each call. For your own program, see the Tool server API.

The tool server also has process_wait and process_close_stdin. The agent tools do not include them: read a process with process_output. The arguments of every tool are in the Tool server API; the schemas of the tools are the authority.

Paths are relative to the working directory, /home/kl/workspace. A path outside it gets an error. Every tool takes an optional tree; the default main is the workspace itself. A workspace that has no activity stops. A running tool call, an open process stream and an inbound connection to a port other than 7788 count as activity. A detached process does not.

Commands and processes

exec without detach is a job. The tool waits and answers exit_code, stdout and stderr. The default limit is 120000 ms (timeout_ms) and the maximum is 600000 ms. At the limit the answer has "timed_out": true and exit_code -1, and the server kills the command and its children. head, tail and quiet keep the answer short.

exec with "detach": true is a process. The tool answers {id} at once. Use the id with process_output, process_write, process_kill and process_list. A process keeps the last 4 MiB of each stream, and the list holds it for 10 minutes after it exits. At most 32 processes run in one workspace.

process_output answers next and next_err. Send them back as since and since_err to read only new output. A stop of the workspace does not lose a process: the server starts it again with the same id, at most 3 times.

Confinement

Each exec runs in a bwrap sandbox. The command sees the home of its tree, read and write. It sees /nix and a few files of /etc read-only, its own /tmp, and the network of the workspace. It does not see /etc/kloudlite, so the agent cannot read the workspace token. For that reason kl is not on the path of exec; run kl from a shell of the workspace. If bwrap cannot start, the command runs without the sandbox.

container_build and container_push run outside the sandbox, so they have the credential that exec lacks. The agent chooses only what to build. The build context and the Dockerfile must be inside the tree. container_build waits up to 600000 ms and keeps the last 40 lines of each stream. The tag and registry rules are those of kl container.

A terminal is not available: exec with "pty": true gets 400. Use SSH.

Tasks

Run a command

Reason for the task: Run a command in a workspace and read its result.

Job set-up

• Access: you.
• Agent tool: exec
• Conditions: the workspace is ready. The tool starts an idle-stopped workspace first.
• References: Tool server API.

Procedure

1. Run the command. Add head or tail to keep a long answer short.

   AI agentCopy

   {"tool": "exec", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b", "cmd": "uname -a"}}

Close-out

1. Make sure that exit_code is 0 and stdout shows the system name.

Run a long command

Reason for the task: Start a command that runs longer than the limit of a job, and read its output while it runs.

Job set-up

• Access: you.
• Agent tool: exec
• Conditions: the workspace is ready.
• References: Tool server API, kloudlite workspaces follow.

Procedure

1. Start the command as a process.

   AI agentCopy

   {"tool": "exec", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b", "cmd": "for i in 1 2 3; do echo $i; sleep 2; done", "detach": true}}

2. Read the output with the id from step 1. Repeat with since set to the next of the last answer.

   AI agentCopy

   {"tool": "process_output", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b", "id": "p1"}}

3. Stop the process if you no longer need it.

   AI agentCopy

   {"tool": "process_kill", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b", "id": "p1"}}

Close-out

1. Show the processes with process_list. Make sure that the process shows exit_code 0, or is gone after a kill.

Change files

Reason for the task: Read code and change it in one step, so that no half edit stays.

Job set-up

• Access: you.
• Agent tool: edit
• Conditions: the workspace is ready.
• References: Tool server API.

Procedure

1. Read the files. paths takes up to 50 files.

   AI agentCopy

   {"tool": "read", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b", "paths": ["src/main.rs", "Cargo.toml"]}}

2. Change the files. All edits succeed or none applies; files takes up to 50 files, each with its edits.

   AI agentCopy

   {"tool": "edit", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b", "files": [{"path": "src/main.rs", "edits": [{"old": "let n = 1;", "new": "let n = 2;"}]}]}}

Close-out

1. Read the file again, or run grep. Make sure that the new text is present.

Troubleshooting