Copy page

Guides

Commands and files

Run shell commands, follow long ones, and move files in and out.

Run a command

Code
curl -X POST https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/exec \
  -H "Authorization: Bearer $KUBI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"command": "node --version"}'

Commands run with bash -lc as the desktop user. If one finishes within wait_s (default 25 s), you get 200 with exit_code, stdout and stderr. If not, you get 202 and an exec id.

Follow a long command

Code
curl "https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/exec/ex_01jb7r2m5k8q3w9x4z6t?until=exit&wait_s=25&tail=true" \
  -H "Authorization: Bearer $KUBI_API_KEY"

This waits up to 25 s for the command to end and returns the last part of the output, where errors usually are. A 5-minute build takes about 12 calls. Stop a command with POST .../exec/{exec_id}/kill.

Set "timeout_s": 0 for a command that should run until you kill it, such as a dev server or a desktop app.

Secrets you saved in the dashboard are in every command's environment, and in /home/user/.config/kubi/secrets.env. Anything running on the screen, your agent included, can read them, so use keys you can revoke.

Upload and download

Code
# upload
curl -X PUT "https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/files?path=/home/user/input.csv" \
  -H "Authorization: Bearer $KUBI_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @input.csv

# download
curl "https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/files?path=/home/user/report.pdf" \
  -H "Authorization: Bearer $KUBI_API_KEY" -o report.pdf

Files up to 64 MiB. List a folder with GET /screens/{id}/dir?path=/home/user/Downloads.

Over MCP, read_file and write_file move one file up to 64 KiB, as text or base64, so the result fits in an agent app's reply. Move bigger files through the API, the SDK or exec.