ready state, you can run shell commands, read and write files, give a service a public HTTPS URL, and open the machine’s desktop. All operations require the machine to be in the ready or running state — check GET /api/v1/machines/:id first if you are not sure.
Run a command
POST /api/v1/machines/:id/run executes a shell command on the machine and waits for it to complete. Requires compute:run.
Run a shell command
Request body
string
required
The shell command to run. Runs inside
bash -c.number
Maximum seconds to wait for the command to finish before the request times out. Defaults to 60.
Response fields
number
The process exit code.
0 indicates success.string
Standard output captured from the command.
string
Standard error captured from the command.
Read a file
GET /api/v1/machines/:id/files?path=<PATH> reads a file from the machine’s filesystem as text or base64. Requires compute:read.
The equivalent MCP tool is read_machine_file.
Write a file
PUT /api/v1/machines/:id/files?path=<PATH> creates or replaces a file on the machine’s filesystem. The request body is the file content. Requires compute:run.
The equivalent MCP tool is write_machine_file.
Expose a port
POST /api/v1/machines/:id/ports gives a service running on the machine a stable public HTTPS URL. Use this to share a local server or preview a build with a team member. Requires compute:run.
The equivalent MCP tool is host_machine_port.
Request body
number
required
The local port number the service is listening on inside the machine.
Response fields
string
The stable public HTTPS URL that forwards to the machine port.
Open the desktop
GET /api/v1/machines/:id/desktop returns a short-lived URL for browser-based desktop access to the machine. Requires compute:admin.
The equivalent MCP tool is get_machine_desktop.