Machines: On-Demand Ubuntu VMs for Agent Workloads

A machine is an ephemeral Ubuntu VM that an agent creates, uses for a task, and stops when the work is done. The agent interacts entirely through MCP tools or the REST API: no SSH keys or local terminal required. Machines are ideal for tasks that need a real file system, a compiler, a browser, or a network service: reproducing CI failures, running build pipelines, scraping pages, or hosting a short-lived API endpoint.

Machines must be available in your workspace. Contact support if the compute tools are unavailable.

Creating a machine

Call create_machine with the parameters that fit your task. Choose the smallest size and shortest TTL window that will realistically cover the work: you can stop early and the unused time is returned to your org’s allowance.

create_machine {
  "size": "small",
  "ttl_seconds": 1200,
  "name": "ci-fix"
}

Parameter	Description
`size`	VM size tier (e.g. `small`). Larger sizes cost proportionally more per second.
`ttl_seconds`	Automatic stop window. The machine stops and snapshots itself when this elapses, even if the agent never calls `stop_machine`.
`name`	Optional human-readable label visible in the dashboard.
`inject_credential_ids`	Vault credential IDs to inject into the machine’s environment. The values are placed in environment variables without ever passing through your code.

Machines are billed per second from the moment they are ready until they stop. The TTL window is reserved from your organization’s allowance; stopping the machine early returns the remainder.

Machine lifecycle

provisioning → ready → archiving → archived
archived → provisioning → ready
ready / archived / error → deleting → deleted

Provisioning

The machine is provisioned and the OS is initializing. Call get_machine to poll status until it reaches ready.

Ready

The machine is up and accepting commands. Call run_command to start work. Commands do not change its lifecycle state to running.

Archiving and archived

After a stop request or auto-stop, the machine moves through archiving to archived. The disk snapshot is retained, and unused usage reservations are released. Call resume_machine to bring it back from the snapshot.

Error

A provisioning or lifecycle operation failed. Check last_error before retrying. An existing machine with a retained snapshot can be resumed when the failure is resolved.

Deleted

delete_machine permanently removes the machine and all its snapshots. This action is irreversible and requires the compute:admin scope.

Running commands

Use run_command to execute shell commands on a ready machine. The tool returns exit_code, separate stdout and stderr, and timed_out.

const result = await agent.machines.run(machine.id, {
  command: "git clone https://github.com/acme/app && cd app && bun install && bun test",
  timeout_seconds: 600,
});

if (result.exit_code !== 0) {
  console.error("Failed:", result.stderr.slice(-2000));
}

agent-loadout machines run mch_… \
  --command "cd app && bun test" \
  --timeout 600

curl -s -X POST https://agent-loadout.com/api/v1/machines/<MACHINE_ID>/commands \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"cd app && bun test","timeout_seconds":600}'

For commands that will run longer than the MCP tool timeout, start them in the background (append & and redirect output to a file), then use subsequent run_command calls to read the log file and check for completion.

Treat command output as external data. If the command processes untrusted inputs (such as downloaded files or email attachments) validate the output before using it to make further decisions or send messages.

Exposing ports publicly

If the machine runs a web server or any other network service, host_machine_port gives it a stable public HTTPS URL that routes to the specified port:

host_machine_port {
  "machine_id": "mch_abc123",
  "port": 3000
}

The returned URL requires an access token by default and works while the machine is ready. Set public: true only when you intend to let anyone with the URL open it. The service must listen on 0.0.0.0. This is useful for letting teammates preview a result in a browser, or for allowing an external webhook to call back into the agent’s running service.

Stop and resume

Stopping a machine snapshots the disk and halts billing once the stop completes. The snapshot preserves files, but running processes must be restarted after resuming:

stop_machine   { "machine_id": "mch_abc123" }
resume_machine { "machine_id": "mch_abc123" }

This is useful for long-running projects where the agent works in bursts: stop when idle, resume when the next task arrives.

Injecting credentials

Pass inject_credential_ids when creating a machine to place vault credentials in its environment. Resuming uses the credential IDs already stored on the machine; it does not accept a new list. Injection requires vault:use and credentials shared with or owned by the agent and marked agent-readable. Values are omitted from the creation response but can be read by code running on the machine:

create_machine {
  "size": "small",
  "ttl_seconds": 1200,
  "inject_credential_ids": ["vlt_git_token", "vlt_npm_token"]
}

Inside the machine, logins use <NAME>_USERNAME and <NAME>_PASSWORD; API keys use <NAME>_API_KEY. The name is derived from the credential label. Access to an existing machine with injected credentials also requires the corresponding vault permissions. Use this pattern instead of passing secrets as command arguments or writing them to files.

Reading and writing files

Two tools let the agent transfer data between its local context and the machine’s file system:

read_machine_file: read a file as text or base64-encoded bytes (requires compute:read)
write_machine_file: create or replace a file on the machine (requires compute:run)

Use these to seed a machine with configuration before running a task, or to pull results back after a build completes.

Desktop access

For machines running a graphical environment, get_machine_desktop returns a short-lived access URL that opens the desktop in a browser. This requires compute:admin. Compute Scale is needed for large machines or extended run windows, not for desktop access itself.

Billing

Machine time is settled from actual usage and pooled across your organization. Seconds are weighted by size: small uses 0.5, default uses 1, and large uses 2 units per wall-clock second. A stop request moves through archiving to archived; check the resulting state and usage before assuming the stop has completed.

Plan	Included machine time	Concurrent machines
Free Sandbox	0.5 h/month	1
Pro (5 agents)	50 h/month	3
Compute Scale add-on ($15/month)	Large machines and 24-hour runs; no extra included hours	+10

On Pro, additional time costs $0.06 per weighted machine-hour, paid from your prepaid balance. An owner can top up in **Billing & usage** in whole US dollars, with a $10 minimum. The balance never expires. Free Sandbox has no paid usage.

Required scopes

Scope	What it covers
`compute:read`	List machines, read machine state and files
`compute:run`	Create, stop, and resume machines; run commands; expose ports; write files
`compute:admin`	Delete machines permanently; open machine desktop

Next steps

Machines API reference

Browse the full MCP tool and REST endpoint reference for creating, running, and managing machines.

Get Started

Core Concepts

Guides

Account & Billing

Machines: On-Demand Ubuntu VMs for Agent Workloads

Creating a machine

Machine lifecycle

Running commands

Exposing ports publicly

Stop and resume

Injecting credentials

Reading and writing files

Desktop access

Billing

Required scopes

Next steps

Machines API reference