Run commands
An agent drives a workspace two ways. The tool server inside every workspace exposes exec, files, watch and the code graph as a plain HTTP API through the ssh tunnel, typed and bounded. Plain ssh is t
An agent drives a workspace two ways. The tool server inside every workspace exposes exec, files, watch and the code graph as a plain HTTP API through the ssh tunnel, typed and bounded. Plain ssh is the other: the same keys, the same audit path, and no second permission model. This page is the ssh way.
One-off commands
ssh -o BatchMode=yes api 'cd ~/workspaces/api && pnpm test -- --reporter=json'BatchMode=yes fails instead of prompting. Exit status and output are the command's own.
Setting up ssh for an agent
- Add the agent's public key to the account it acts for: Authentication.
- On the machine the agent runs on, install
kl-connect, log in as that account, and write the config:
kl-connect loginkl-connect ws ssh-config- Use the workspace's name as the ssh host.
The ProxyCommand fetches a fresh connect ticket per connection, so a long-running agent needs no token refresh logic of its own.
Long-running processes
Start a process that outlives the session with a multiplexer or nohup; a workspace keeps running until it is stopped.
ssh api 'cd ~/workspace && nohup pnpm dev --port 3000 > ~/dev.log 2>&1 &'ssh api 'tail -n 50 ~/dev.log'Working directory
The tree is at /home/kl/workspace; /home/kl is this workspace's own volume, not shared with
any other workspace. Write scratch anywhere under the home; there is no other workspace to leak
into.
Creating workspaces from an agent
Everything on /v1 is a bearer call. A typical loop: create → poll state → ssh-config → work → push with a message → stop or delete.
WS=$(curl -sS https://dev.kloudlite.io/v1/workspaces -H "Authorization: Bearer $KL_TOKEN" \ -H 'content-type: application/json' \ -d '{"name":"task-42","quota_gb":20,"repo":"[email protected]:acme/api.git","branch":"main","packages":["nodejs@22","pnpm"]}' | jq -r .id)until [ "$(curl -sS https://dev.kloudlite.io/v1/workspaces/$WS -H "Authorization: Bearer $KL_TOKEN" | jq -r .state)" = ready ]; do sleep 3; donekl-connect ws ssh-configssh -o BatchMode=yes task-42 'cd ~/workspaces/task-42 && pnpm install && pnpm test'