Agent tools

Lists the tools of the Kloudlite agent tool set, with the arguments and the route of each.

Last updated 23 Oct 2026

On this page

web_fetch
web_search
read
write
edit
patch
glob
grep
exec
process_list
process_output
process_write
process_kill
watch
watch_poll
watch_stop
container_build
container_push
workspace_list
workspace_get
workspace_create
workspace_clone
workspace_restore
workspace_start
workspace_stop
workspace_delete
workspace_snapshot
worktree_add
worktree_drop
packages_list
session_current
session_connect
session_disconnect
env_list
env_get
env_wait
service_logs
env_delete
env_start
env_stop
env_create
env_clone
env_snapshot
env_restore
service_add
service_update
service_remove
volume_list
volume_history
volume_refs
volume_delete
snapshot_delete
builder_status
quota
requests_list
request_get
request_create
regions
packages_add
packages_remove
packages_update
intercept
release
workspace_ask
task_add
task_update
task_list
workspace_tasks
scratch_bash
scratch_read
scratch_write
session_use
session_pick

`web_fetch`

Reads the text of one web page from its URL.

No route. The tool fetches the URL itself.

Argument	Type	Required	Meaning
`url`	string	yes	An absolute http(s) URL.
`max_chars`	number	no	Truncate the result at this number of characters. The default is 50000.
`maxChars`	number	no	The other spelling of `max_chars`.

`web_search`

Searches the web and returns titles, URLs and snippets.

No route. The tool calls a search service.

Argument	Type	Required	Meaning
`query`	string	yes	What to search for.
`count`	integer	no	The number of results. The default is 5. The maximum is 10.

`read`

Reads text files of a workspace, with line numbers.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`write`

Creates or overwrites one file of a workspace.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`edit`

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

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`patch`

Applies a unified diff to the files of a workspace.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`glob`

Lists the files of a workspace that match a glob.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`grep`

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

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`exec`

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

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`process_list`

Lists the detached processes of a workspace.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`process_output`

Reads the output of a detached process from a byte offset.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`process_write`

Writes to the input of a detached process.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`process_kill`

Stops a detached process and its children.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`watch`

Starts a watch on files of a workspace, or on a command, and returns its id.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`watch_poll`

Reads the events that a watch has seen since an index.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`watch_stop`

Stops a watch.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`container_build`

Builds a container image from the files of a workspace and pushes it to your registry.

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`container_push`

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

Route: tool server.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`workspace_list`

Lists the workspaces of the session, or of one team.

Route: GET /v1/workspaces.

Argument	Type	Required	Meaning
`team`	string	no	The team slug. Omit it for your own.

`workspace_get`

Reads the state of one workspace. Poll it after each lifecycle call.

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

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`workspace_create`

Creates a workspace in the region of the team. In a session, the workspace is created in the session and is managed by it. It returns at once.

Route: POST /v1/sessions/{id}/workspaces in a session, else POST /v1/workspaces.

Argument	Type	Required	Meaning
`name`	string	yes	The name.
`quota_gb`	number	yes	The disk size in GB.
`image`	string	no	The image.
`packages`	array of string	no	Package entries, `attr` or `attr@version`.
`team`	string	no	The team slug. Omit it for your own. A session uses its own team instead.

`workspace_clone`

Copies the current state of a workspace into a new workspace.

Route: POST /v1/workspaces/{id}/clone.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).
`name`	string	yes	The name.
`task`	string	no	What the clone is for. Use at most 200 characters.

`workspace_restore`

Creates a workspace from a snapshot.

Route: POST /v1/workspaces/restore.

Argument	Type	Required	Meaning
`name`	string	yes	The name.
`snapshot_id`	string	yes	A volume name, `name@N` or a snapshot id.
`team`	string	no	The team whose volumes a name is read from. Required for the volume of a team.
`image`	string	no	The image.
`packages`	array of string	no	Package entries, `attr` or `attr@version`.
`quota_gb`	number	no	The disk size in GB.

`workspace_start`

Starts a stopped workspace.

Route: POST /v1/workspaces/{id}/start.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`workspace_stop`

Stops a workspace that is up, after it makes a snapshot.

Route: POST /v1/workspaces/{id}/stop.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`workspace_delete`

Deletes a workspace for good. In a session, the workspace is deleted in the session.

Route: DELETE /v1/sessions/{id}/workspaces/{workspace} in a session, else DELETE /v1/workspaces/{id}.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`workspace_snapshot`

Makes a snapshot of the workspace in its history.

Route: POST /v1/workspaces/{id}/snapshots.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).
`message`	string	no	A note for the snapshot.
`volume`	string	no	The volume name. Required on the first push of a volume.

`worktree_add`

Adds a worktree to a workspace.

Route: POST /v1/workspaces/{id}/trees.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).
`name`	string	yes	The name.

`worktree_drop`

Removes a worktree from a workspace.

Route: DELETE /v1/workspaces/{id}/trees/{name}.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).
`name`	string	yes	The name.

`packages_list`

Lists the packages that a workspace declares.

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

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`session_current`

Shows the session of this laptop and its environment.

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

No arguments.

`session_connect`

Connects the session to an environment of its team.

Route: PUT /v1/sessions/{id}/environment.

Argument	Type	Required	Meaning
`environment`	string	yes

`session_disconnect`

Disconnects the session from its environment.

Route: PUT /v1/sessions/{id}/environment.

No arguments.

`env_list`

Lists the environments, or those of one team.

Route: GET /v1/environments.

Argument	Type	Required	Meaning
`team`	string	no	The team slug. Omit it for your own.

`env_get`

Reads the services, the state and the intercepts of an environment.

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

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).

`env_wait`

Waits until an environment settles after a change, then returns its state.

Route: GET /v1/environments/{id}, repeated.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).
`timeout`	number	no	Seconds.
`timeout_ms`	number	no	Milliseconds (the other spelling of `timeout`).

`service_logs`

Reads the recent logs of one service of an environment.

Route: GET /logs/{env}/{service} on the builder gate.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).
`service`	string	yes	The service.
`tail`	number	no
`since`	number	no
`previous`	boolean	no

`env_delete`

Deletes an environment for good.

Route: DELETE /v1/environments/{id}.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).

`env_start`

Starts a stopped environment.

Route: POST /v1/environments/{id}/start.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).

`env_stop`

Stops an environment that is up.

Route: POST /v1/environments/{id}/stop.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).

`env_create`

Creates an environment of services, or one that grows from a snapshot.

Route: POST /v1/environments.

Argument	Type	Required	Meaning
`name`	string	yes	The name.
`snapshot_id`	string	no	The id of a snapshot.
`services`	array of object	no
`team`	string	no	The team slug. Omit it for your own.
`quota_gb`	number	no	The disk size in GB.

`env_clone`

Creates a new environment from the live state of an environment, or from one of its snapshots.

Route: POST /v1/environments/{id}/clone.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).
`name`	string	yes	The name.
`snapshot_id`	string	no	The id of a snapshot.
`team`	string	no	The team slug. Omit it for your own.
`services`	array of object	no
`region`	string	no
`quota_gb`	number	no	The disk size in GB.

`env_snapshot`

Makes a snapshot of an environment in its history.

Route: POST /v1/environments/{id}/snapshots.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).
`message`	string	no	A note for the snapshot.
`volume`	string	no	The volume name. Required on the first push of a volume.

`env_restore`

Puts an environment back to one of its own snapshots. Data written since is lost.

Route: POST /v1/environments/{id}/restore.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).
`snapshot_id`	string	yes	The id of a snapshot.
`discard`	array of string	no	Names of the services from the 409 `lost` list whose data you accept losing.

`service_add`

Adds one service to an environment. It fails if the name exists.

Route: GET /v1/environments/{id}, then PATCH /v1/environments/{id}.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).
`service`	object	yes	The `command`, `env` and `mounts` fields default to empty.

`service_update`

Replaces one existing service of an environment, matched by name.

Route: GET /v1/environments/{id}, then PATCH /v1/environments/{id}.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).
`service`	object	yes	The `command`, `env` and `mounts` fields default to empty.

`service_remove`

Removes one service from an environment.

Route: GET /v1/environments/{id}, then PATCH /v1/environments/{id}.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).
`name`	string	yes	The name.

`volume_list`

Lists the volumes, with an optional kind and owner.

Route: GET /v1/volumes.

Argument	Type	Required	Meaning
`kind`	string	no	The kind.
`owner`	string	no	The owner: a person handle or a team slug.

`volume_history`

Lists the snapshots of a volume.

Route: GET /v1/volumes/{name}/history.

Argument	Type	Required	Meaning
`volume`	string	yes	The volume name.

`volume_refs`

Reads the branch tips of a volume.

Route: GET /v1/volumes/{name}/refs.

Argument	Type	Required	Meaning
`volume`	string	yes	The volume name.

`volume_delete`

Deletes a detached volume for good.

Route: DELETE /v1/volumes/{name}.

Argument	Type	Required	Meaning
`volume`	string	yes	The volume name.

`snapshot_delete`

Deletes one snapshot of a volume.

Route: DELETE /v1/volumes/{name}/snapshots/{id}.

Argument	Type	Required	Meaning
`volume`	string	yes	The volume name.
`snapshot`	string	yes

`builder_status`

Shows the state of the image builder of a team.

Route: GET /v1/builders/me.

Argument	Type	Required	Meaning
`team`	string	no	The team slug. Omit it for your own.

`quota`

Shows the ceilings and the current use of an owner.

Route: GET /v1/quota.

Argument	Type	Required	Meaning
`owner`	string	no	The owner: a person handle or a team slug.

`requests_list`

Lists the requests of the person and of their teams.

Route: GET /v1/requests.

Argument	Type	Required	Meaning
`owner`	string	no	The owner: a person handle or a team slug.

`request_get`

Shows one request and its decision.

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

Argument	Type	Required	Meaning
`id`	string	yes

`request_create`

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

Route: POST /v1/requests.

Argument	Type	Required	Meaning
`owner`	string	no	The team slug. Omit it for the person's own.
`kind`	string, one of quota, access, region, other	yes	The kind.
`reason`	string	yes	Why the person asks.
`quota`	object	no	The new ceilings that you want. Give only the dimensions that change.
`access`	object	no
`region`	string	no	The region the team moves to (only while the team has nothing).
`title`	string	no	The title.
`body`	string	no	The text.

`regions`

Lists the regions in which a team can live.

Route: GET /v1/regions.

No arguments.

`packages_add`

Declares packages on a workspace. An entry with the same attribute replaces the old entry.

Route: GET /v1/workspaces/{id}, then PATCH /v1/workspaces/{id}.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).
`packages`	array of string	yes	Package entries, `attr` or `attr@version`.

`packages_remove`

Removes declared packages from a workspace.

Route: GET /v1/workspaces/{id}, then PATCH /v1/workspaces/{id}.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).
`packages`	array of string	yes	Package entries, `attr` or `attr@version`.

`packages_update`

Resolves the package pins of a workspace again, to the newest matching versions.

Route: POST /v1/workspaces/{id}/packages/update.

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).

`intercept`

Sends the traffic of an environment service to a workspace.

Route: POST /v1/environments/{id}/intercepts.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).
`service`	string	yes	The service.
`workspace`	string	yes	The workspace id (`ws-…`).
`ports`	array of object	no	Port remaps: `service` is the port callers dial on the environment service, `workspace` the port the workspace listens on. Omit to forward each port to the same number.

`release`

Gives an intercepted service back to its own program.

Route: DELETE /v1/environments/{id}/intercepts/{service}.

Argument	Type	Required	Meaning
`env`	string	yes	The environment id (`env-…`).
`service`	string	yes	The service.

`workspace_ask`

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

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

Argument	Type	Required	Meaning
`workspace`	string	yes	The workspace id (`ws-…`).
`request`	string	yes
`for`	string	no	The id of your own board task this ask serves.

`task_add`

Adds a task to the board of the agent.

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

Argument	Type	Required	Meaning
`title`	string	yes	The title.
`priority`	integer	no	Lower runs first.
`depends_on`	array of string	no
`note`	string	no

`task_update`

Changes a task on the board of the agent.

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

Argument	Type	Required	Meaning
`id`	string	yes
`title`	string	no	The title.
`priority`	integer	no	Lower runs first.
`depends_on`	array of string	no
`state`	string, one of queued, running, blocked, done, failed	no	The state to list.
`note`	string	no
`summary`	string	no
`verified`	string	no

`task_list`

Lists the tasks on the board of the agent.

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

No arguments.

`workspace_tasks`

Lists the tasks on the board of one workspace.

No route. The tool reads the board of the workspace.

Argument	Type	Required	Meaning
`workspace`	string	no	The workspace id (`ws-…`). Leave it out to get every workspace board.

`scratch_bash`

Runs a command in the scratch folder of the session, not in a workspace.

No route. The tool runs in the session.

Argument	Type	Required	Meaning
`command`	string	yes
`timeout`	number	no	In seconds. The default is 120. The maximum is 600.
`timeout_ms`	number	no	The same limit in milliseconds (the other spelling of `timeout`); give one of them.

`scratch_read`

Reads a file of the scratch folder of the session, not of a workspace.

No route. The tool runs in the session.

Argument	Type	Required	Meaning
`path`	string	yes
`offset`	integer	no
`limit`	integer	no	The most items to return.

`scratch_write`

Writes a file of the scratch folder of the session, not of a workspace.

No route. The tool runs in the session.

Argument	Type	Required	Meaning
`path`	string	yes
`content`	string	yes

`session_use`

Picks the session of this laptop. It can connect the session to an environment, and create the session or the environment.

Route: GET /v1/sessions, PUT /v1/sessions/{id}/environment, and POST /v1/sessions or POST /v1/environments when it creates.

Argument	Type	Required	Meaning
`team`	string	no	The team slug. Omit it for your own.
`name`	string	no	An existing session of yours, by name or id. It picks the session and never creates one.
`environment`	string	no	An existing environment, by id or name, to connect the session to.
`new_environment`	string	no	The name of an environment to create and connect. Not with `environment`.

`session_pick`

Picks the session that the tools drive. It is the only tool until you pick a session.

No route. The tool runs in kloudlite.

Argument	Type	Required	Meaning
`id`	string	yes	The session name or id.