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 are feature-flagged. The compute:* scopes and list_machines tool will return an error until machines are enabled in your workspace. Contact support or check your plan’s feature list if the 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

created → ready → running → stopped → deleted

Created

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.

Running

A command is executing. Long-running commands can be started in the background; poll for output periodically.

Stopped

stop_machine has been called (or the TTL elapsed). The disk is snapshotted and billing pauses. The machine is not deleted — call resume_machine to bring it back from the snapshot.

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 the exit code and combined output.

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>/run \
  -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 is accessible from the public internet for as long as the machine is running. 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. The machine is not deleted — resume it later from the exact state it was in:

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 or resuming a machine to place vault credentials in the machine’s environment variables. The credential values are injected directly by the platform — they never appear in the MCP tool call or in your application code:

create_machine {
  "size": "small",
  "ttl_seconds": 1200,
  "inject_credential_ids": ["cred_git_token", "cred_npm_token"]
}

Inside the machine, the credentials are available as environment variables named after the credential. 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 the compute:admin scope and the Compute Scale add-on for large machines with extended run windows.

Billing

Machines are billed per second from the moment they reach ready until they reach stopped or deleted. Size affects the per-second rate: larger sizes cost proportionally more. Machine time is pooled across your organization.

Plan	Included machine time	Concurrent machines
Free Sandbox	0.5 h/month	1
Pro (5 agents)	50 h/month	3
Compute Scale add-on	+Large machines, 24-hour runs, +10 concurrent	€15/month

Additional machine time beyond your pool is available at €0.06 per machine-hour.

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

​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

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