Agent tools

Conventions

• A workspace id starts with ws-, an environment id with env-. An id or a name works. The list actions give both.
• Most tools are one per resource. The action argument picks the verb, and the Actions table of a tool lists the verbs. A call without an action that the tool has is refused with the names of the valid ones.
• A call that lacks an argument of its action is refused with the schema of that action.
• A workspace that workspace makes with action set to create in a desk is managed: the desk deletes it when the desk is deleted.
• The actions create, start, and restore of workspace and env, start of run and desk, create of capsule, and add and update of service take wait: true. They answer when the object has settled, or at soft_ms (25 000 by default, 600 000 at most) with a hand-off. See Waits and hand-off.
• The wait actions take timeout_ms (25 000 by default, 900 000 at most) and wait for an object that already exists. At the limit they answer the object with timed_out: true; call them again. A service with failing: true does not come up by waiting: read its message, fix the cause, and change the service again.
• secret_set never prints the value back. The agent sets, lists, and deletes secrets with secret_set, secret_list, and secret_delete. It can use them in variables, but no tool reads a value.
• service with action set to logs takes tail (default 200, maximum 2000), since in seconds (maximum 86400), and previous for the run before a crash. It starts an idle-stopped environment first. When an intercept holds the service, the answer names the workspace that serves it.
• volume actions get and delete take the id of a volume, never its name. Read the id from the list action, or from the volume field of the workspace or the environment.
• The first snapshot of a volume gives volume, its name. Restore and copy take a reference in snapshot_id: name, name@N, or a snapshot id. A snapshot answer names its volume in volume. See Names and versions.
• When env with action set to restore answers 409 with lost, the agent names services in discard only after the developer accepts the loss.
• A command or build that runs longer than soft_ms (25 seconds by default) in exec or container_build is promoted to a process. Follow it as the Waits and hand-off paragraph says.
• process with action set to wait on an id that ended more than 10 minutes ago, or never existed, answers state: "gone" and a hint. It is not an error.

Waits and hand-off

A call that waits never blocks for long. At soft_ms it answers {promoted: true, id, kind, next, next_err} and the work goes on. The kind says how to resume it.

Both MCP doors speak the 2026-07-28 revision and 2025-era clients. A client that declares the io.modelcontextprotocol/tasks extension gets a task for a call that runs past 10 seconds and polls tasks/get; it never sees promoted. Other clients keep the loop above.

For a platform object the platform does the work, and next and next_err are 0. A wait action ends at timeout_ms with timed_out: true.

Scopes

An agent does not hold every tool. The tools that it holds depend on where it runs.

kode mcp serves the tools of both scopes in one list, and each tool takes the workspace or env that it acts on. The harness splits them:

• The main desk creates, starts, stops, and deletes workspaces and environments. It holds packages with list but no other package action, and no intercept.
• The desk of a workspace holds the code tools, packages, intercept, service, and workspace with stop and snapshot. It reports to the main desk with main_tell.
• A subagent runs in a clone of a workspace. It holds the tools of that workspace without workspace stop, intercept, the board, workspace_ask, main_tell, and subagent.

read

Reads text files of a workspace, with line numbers.

A PNG, JPEG, GIF, or WebP file comes back as an image that the agent sees: an MCP image block on the laptop and remote doors, an image in the tool result of a desk's own agent. The tool server decides the type from the first bytes of the file, not from its name. The limit is 5 MB of base64 for one image, and for all the images of one paths call. A PNG or JPEG over it is downscaled to fit, and the answer says downscaled_from. A GIF or WebP over it answers its size, mime, and a hint. Any other binary file answers its size and mime.

Route: tool server.

write

Creates or overwrites one file of a workspace.

Route: tool server.

The limit is 10 MiB of file content. To copy a larger file, or any file from another workspace, use transfer: its bytes go from one tool server to the other and never through the agent.

edit

Replaces exact text in the files of a workspace. If one edit does not apply, none is written.

Route: tool server.

glob

Lists the files of a workspace that match a glob.

Route: tool server.

grep

Searches the contents of the files of a workspace with a regular expression.

Route: tool server.

exec

Runs a command in a workspace and returns its output and exit code, or starts it as a detached process.

Route: tool server.

The extra argument notify is never, on_failure (the default), or always. It sets when the desk reports the end of a detached or promoted process as a notice. The tool server does not see it.

Any tool answer can start with notices, a list of sentences about processes that ended since the last answer. A process that crashed arrives there with its command and the last lines of its stderr. A process that a restart killed arrives there with the restart time. The notices ride as a second content item of the answer, after the result, and each arrives once.

A process that exits on its own is never restarted; the desk reports it. A detached process that a workspace stop or restart killed starts again with the workspace, with the same id. Its output then opens with [restarted <time>: <reason>]. relaunch: false on exec opts one process out: after a restart it is listed as killed_by_restart instead. A workspace that is restored or cloned relaunches no process of its source.

process

Controls the detached processes of a workspace. A long exec job becomes one.

Route: tool server.

A process that a workspace restart killed and that did not start again is answered with state: "killed_by_restart" and restarted_at. list shows it for an hour, and wait and output answer it with a hint to run the command again.

watch

Watches files of a workspace, or a command, for changes.

Route: tool server.

container_build

Builds a container image from the files of a workspace and pushes it to your registry. The image carries no provenance or SBOM attestation.

Route: tool server.

With no connected registry the tool fails with error: "no_registry", a hint to connect one in the console under Connectors, and registries. A registry that is not connected fails with error: "unknown_registry", the name, and registries.

container_push

Copies an image that the registry holds to more names, without a build.

Route: tool server.

workspace

Creates, runs, copies, and removes workspaces.

Route: by action.

workspace_vars

Reads and sets the variables of a workspace.

Route: by action.

worktree

Adds or drops a worktree of a workspace.

Route: by action.

packages

Reads and changes the packages of a workspace.

Route: by action.

desk

Shows, picks, creates, and manages desks.

Route: by action.

env

Creates, runs, copies, and removes environments.

Route: by action.

service

Adds, changes, removes, and reads the logs of environment services.

Route: by action.

intercept

Sends the traffic of an environment service to a workspace, or gives it back.

Route: by action.

volume

Lists, reads, and deletes volumes.

Route: by action.

snapshot

Deletes a snapshot of a volume.

Route: by action.

quota

Shows the ceilings and the current use of an owner.

Route: GET /v1/quota.

requests_list

Lists the requests of the person and of their teams.

Route: GET /v1/requests.

request_get

Shows one request and its decision.

Route: GET /v1/requests/{id}.

request_create

Asks an administrator for quota, access, a region, or anything else. The decision comes later.

Route: POST /v1/requests.

regions

Lists the regions in which a team can live.

Route: GET /v1/regions.

No arguments.

download

Hands one file of a workspace to the person. Only the owner of the workspace gets an answer, and the file is at most 200 MB. Nothing in the answer is a credential.

• url opens the file in the Kode console. The person must be signed in as the owner. Images, PDFs and text show in the browser; other files download.
• On an MCP door the answer also has a resource_link block with uri. The client reads the file with resources/read on its own connection, at most 7.5 MB that way.

The bytes go from the tool server to the browser or the client when they are read, never through the agent. A device workspace is read from its machine at that time, so the machine must be online.

Route: POST /v1/workspaces/{id}/file-link.

Answer: {url, uri, name, size, mime, note}, and a resource_link content block on an MCP door.

MCP resources

Every MCP door (/mcp and kode mcp) declares the resources capability. resources/templates/list answers one template, kode://workspace/{workspace}/file/{path} (?tree=NAME for a worktree); resources/list answers none. resources/read answers contents: [{uri, mimeType, text}] for a text file and [{uri, mimeType, blob}] (base64) for any other. It reads as the connection's own person, owner only, in the teams the connection may act in, and takes no desk. A file over 7.5 MB (10 MB of base64) is refused with a sentence that names download.

transfer

Copies one file from a workspace to another workspace of yours, or to another path of the same workspace. The file is at most 200 MB and can hold any bytes. The bytes go from the tool server of the source to the tool server of the destination, in ranges of 4 MiB, and never through the agent or the MCP client. The destination appears whole when the last range is written, or not at all. A destination that exists is refused unless overwrite is true. Both workspaces must be ready; a device workspace's machine must be online.

Route: tool server, both workspaces, found through GET /v1/workspaces/{id}/tools. That route answers the owner alone, so a workspace of another person is 404.

Answer: {from: {workspace, path}, to: {workspace, path, created}, bytes}. A refusal starts with from: or to: to say which side refused.

devices

Lists your own machines, the devices that run device workspaces. The id is what workspace create takes as device. Each row has id, name, os, arch, enabled, account (a handle or a team), online, last_seen_at and the workspaces the device reports. It never lists a token or the hardware id. Starting, connecting and removing a device are done on the machine.

Route: GET /v1/devices.

No arguments.

capsule

Runs one command in an isolated container.

Route: by action.

pipeline

Saves, reads, and deletes pipelines and their versions.

Route: by action.

webhook_rotate

Makes a new webhook secret for a pipeline. The old URL stops at once. The answer holds the new webhookUrl once.

Route: POST /v1/pipelines/{owner}/{name}/webhook/rotate.

run

Starts, reads, waits for, and cancels pipeline runs.

Route: by action.

secret_set

Stores a secret value and replaces an existing one. The value is never printed back. The answer holds name and updatedAt only. A workspace or service reads the secret through an environment value that is exactly ${{ secrets.NAME }}. The harness keeps each desk transcript and stores this call with value replaced by ***; the model's context still holds the value for the turn.

Route: PUT /v1/secrets/{owner}/{name}, or PUT /v1/secrets/{owner}/mine/{name} with mine.

secret_list

Lists the names of the secrets of an owner, with the date and the author of the last change. It never shows a value.

Route: GET /v1/secrets/{owner}, or GET /v1/secrets/{owner}/mine with mine.

secret_delete

Deletes one secret. The call answers 409, and names the referrers, while a workspace, capsule, service, or pipeline uses it.

Route: DELETE /v1/secrets/{owner}/{name}, or DELETE /v1/secrets/{owner}/mine/{name} with mine.

connector_list

Lists the connectors of an owner, with the provider, the kind, the account, and the state of each. It is read only. Connecting happens in the web console.

Route: GET /v1/connectors.

status

Answers the notices not yet delivered on this connection, and a short summary of what runs. It lists the workspaces of the desk and their processes. It also gives lifecycle notices: a restart, a stop, an error, and a change of the environment. A restarted bench still reports the idle stops and evictions it missed. Call it once at the start of each turn, before other work.

No route. The tool reads the desk's notice queue, GET /v1/workspaces, the desk's environment and process_list of every workspace a tool touched in the last hour.

Result: {notices, workspaces: [{name, state}], environment: {name, state} | null, processes: [{workspace, id, cmd}]}. A notice is delivered once: a second call without all does not repeat it. Notices also ride on any other tool answer, as before.

workspace_ask

Gives a goal to the desk of a workspace. The answer arrives later as a message.

No route. The tool sends a message to the desk of the workspace.

question

Asks the developer a question and waits for the answer.

No route. The tool puts the question on the card of the desk and returns the option that the developer selects.

main_tell

Tells the main desk that a task is done, blocked, or needs something.

No route. The tool sends a message to the main desk. Use it from the desk of a workspace.

task

Keeps the board of the agent, which the developer follows.

No route. The tool reads and writes the board of the agent.