> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-loadout.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Machines: On-Demand Ubuntu VMs for Agent Workloads
> Spin up ephemeral Ubuntu VMs, run shell commands, expose ports publicly, and stop when done. Billed per second; snapshots let you pause and resume.
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
```
The machine is provisioned and the OS is initializing. Call `get_machine` to poll status until it reaches `ready`.
The machine is up and accepting commands. Call `run_command` to start work.
A command is executing. Long-running commands can be started in the background; poll for output periodically.
`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.
`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.
```typescript TypeScript theme={null}
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));
}
```
```bash CLI theme={null}
agent-loadout machines run mch_… \
--command "cd app && bun test" \
--timeout 600
```
```bash REST API theme={null}
curl -s -X POST https://agent-loadout.com/api/v1/machines//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
Browse the full MCP tool and REST endpoint reference for creating, running, and managing machines.