> ## 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 API — Provision and Manage Agent Linux VMs

> Create, list, stop, resume, and delete ephemeral Ubuntu VMs for your agent. Billing runs per second from start until the machine is stopped.

Machines are ephemeral Ubuntu VMs provisioned on demand for your agent. Billing starts the moment a machine moves to `running` and stops the second you stop or delete it. Keep machines short-lived: choose the smallest size and shortest TTL that fits the task, and stop early to return unused time to your org's allowance.

<Info>
  Machines must be enabled in your workspace before the compute endpoints and MCP tools are available. Contact support or check your plan's feature flags if you do not see this option.
</Info>

## List machines

`GET /api/v1/machines` returns all machines belonging to the agent's token. Requires **compute:read**.

```bash title="List machines" theme={null}
curl -s https://agent-loadout.com/api/v1/machines \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

### Response fields

<ResponseField name="id" type="string">
  Unique machine identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable label set at creation.
</ResponseField>

<ResponseField name="state" type="string">
  Current lifecycle state: `creating`, `ready`, `running`, `stopped`, or `deleted`.
</ResponseField>

<ResponseField name="size" type="string">
  Machine size class (e.g. `small`).
</ResponseField>

<ResponseField name="charged_time_seconds" type="number">
  Total billable seconds accumulated so far.
</ResponseField>

<ResponseField name="auto_stop_at" type="string">
  ISO 8601 timestamp when the machine will be automatically stopped if still running.
</ResponseField>

## Get one machine

`GET /api/v1/machines/:id` returns the current state and auto-stop time for a single machine. Requires **compute:read**.

## Create a machine

`POST /api/v1/machines` provisions a new Ubuntu VM. Requires **compute:run**.

```bash title="Create a machine" theme={null}
curl -s -X POST https://agent-loadout.com/api/v1/machines \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"size":"small","ttl_seconds":1200,"name":"ci-fix"}'
```

### Request body

<ParamField body="size" type="string">
  Machine size class. Start with `small` for most tasks.
</ParamField>

<ParamField body="ttl_seconds" type="number">
  Maximum lifetime in seconds before the machine is automatically stopped. The remaining window is returned to your org's allowance when you stop early.
</ParamField>

<ParamField body="name" type="string">
  Human-readable label for the machine. Useful for identifying it in the dashboard.
</ParamField>

<ParamField body="inject_credential_ids" type="array">
  IDs of vault credentials to inject into the machine's environment. Values are placed directly on the machine — they are never returned to the caller or visible in the API response.
</ParamField>

## Stop a machine

`POST /api/v1/machines/:id/stop` snapshots the disk and stops the billing clock. The machine can be restarted later with `resume`. Requires **compute:run**.

## Resume a machine

`POST /api/v1/machines/:id/resume` restarts a stopped machine from its last snapshot. Requires **compute:run**.

## Delete a machine

`DELETE /api/v1/machines/:id` permanently deletes the machine and all its snapshots after confirmation. This action cannot be undone. Requires **compute:admin**.

## MCP tools for machines

| Tool             | Scope required | Description                                 |
| ---------------- | -------------- | ------------------------------------------- |
| `list_machines`  | compute:read   | Machines with state and charged time        |
| `get_machine`    | compute:read   | Machine state and auto-stop time            |
| `create_machine` | compute:run    | Start a fresh Ubuntu VM or fork one         |
| `stop_machine`   | compute:run    | Snapshot disk and stop billing              |
| `resume_machine` | compute:run    | Restart a stopped machine from its snapshot |
| `delete_machine` | compute:admin  | Permanently delete after confirmation       |

<Tip>
  Always stop machines as soon as your task completes. Unused TTL is returned to the org's compute allowance immediately when the machine stops.
</Tip>