# Computers

A computer is where a worker runs commands and keeps files, either the workspace's Linux computer or a Mac a person paired.

A worker needs somewhere to work. It runs commands and writes files. That place is a computer. A workspace has one Linux computer that Little Worker runs for it, and each person can also pair their own Mac.

A computer is an environment in Claude Managed Agents. This page explains the two kinds, which one a task uses, what a computer keeps, and the record Little Worker writes of the work on each.

## Two kinds of computer

`GET /computers` lists the computers workers can use. Each has a `scope` that is always `organization`, because the workspace shares its computers.

| Kind | `config.type` | What it is |
| --- | --- | --- |
| The Linux computer | `cloud` | A machine Little Worker starts and stops for the workspace. A workspace has at most one active. |
| A Mac | `self_hosted` | A Mac that a person paired in the Little Worker Mac app. It joins the list when it is paired. |

A computer has a `name`, a `description`, labels in `metadata`, a `status`, and an `archived_at` that is `null` while it is in use. Its id starts with `computer_`. Archived computers are listed only with `include_archived=true`.

### The Linux computer

Make it with `POST /computers`. Little Worker runs it, so you never start a runner or hold a key for it. The runner is the program on a computer that takes the next tool call, runs it, and sends back the result.

```bash
curl https://core.thelittleworker.com/api/v1/computers \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19" \
  -H "content-type: application/json" \
  -d '{
    "name": "Workspace computer",
    "config": { "type": "cloud", "packages": { "pip": ["pandas==2.2.0"], "apt": ["jq"] } }
  }'
```

- **One at a time.** A workspace may have one active Linux computer. Another is `409` with `error_code` `computer_conflict`: archive the first one before you make another.
- **Status.** `status` is `provisioning`, `ready`, `stopping`, `stopped`, `starting`, `recovering` or `failed`.
- **It stops and starts by itself.** Little Worker stops the computer after 15 idle minutes. A stopped computer starts again when a task's tool call needs it. It lasts until you archive or delete it.
- **Packages.** `config.packages` lists what to install before work. The managers run in this order: `apt`, `cargo`, `gem`, `go`, `npm`, `pip`. Each lists up to 100 names, and a name can pin a version the way its manager does, such as `hyperfine@1.18.0`, `rails:7.1.0` or `pandas==2.2.0`. Unpinned means the latest. They are installed when the computer is made, started or recreated. A change with `POST /computers/{computer_id}` replaces the whole list, and takes effect the next time the computer starts or is recreated.
- **Networking is read only.** `config.networking` is `limited`, with an empty `allowed_hosts`, and `allow_mcp_servers` is always `true`. `allow_package_managers` is `true` when the computer lists packages. The websites a worker may reach are set on the worker, not on the computer. A write to `networking` is `400`.

### A Mac

A Mac joins when someone pairs it in the Mac app. `POST /computers` with `config.type` `self_hosted` is `400`. The Mac app runs the Mac's own runner, and Little Worker never stops a Mac. A Mac takes no `packages`: sending them is `400`.

## Which computer a task uses

A task does not pick a computer. A worker's tools decide:

- Commands and files go to the workspace's Linux computer. A worker's first tool call that needs a computer uses it.
- Tools in the `local_device` group act on a Mac a person paired. A step on a Mac asks as the Mac's own settings say.

A task's `computer_id` is read only: it shows the computer the task last ran on, and is `null` when the task never used one. You may send a `computer_id` when you give a task, but it must name one of the workspace's own active computers, or the answer is `400`. It does not pick where the task runs.

Every task of the workspace shares the Linux computer, and so shares its files. A task's own files sit in a folder of its own, under `<workspace>/.little-worker/tasks/<task_id>/`. On the Linux computer, `<workspace>` is `/data/workspace`. That folder holds the task's skills, memory stores, uploaded files and repositories. The runner makes it at the task's first call there, and removes it after a last sync of up to 30 seconds when the task stops running there. A Mac does not make these folders yet.

## Work records

When a task uses a computer, Little Worker writes a **work record** of it. A record is one running stretch of a task on a computer: it opens at the task's first tool call there, and is `stopped` when the task stops running there with no call open. The task's next call opens a new record. A task that never uses a computer has none. Its id starts with `work_`.

`state` moves through these values, and each step sets its timestamp once:

| `state` | What it means |
| --- | --- |
| `queued` | The call waits. No runner has taken it yet. |
| `starting` | The computer took it. |
| `active` | A call started. |
| `stopping` | A stop was asked for. |
| `stopped` | The record is closed. |

A record has `computer_id`, a `data` of `{ "type": "task", "id" }` naming the task, the times `created_at`, `acknowledged_at`, `started_at`, `latest_heartbeat_at`, `stop_requested_at` and `stopped_at`, and `metadata`. Its `secret` is always `null`. The runner takes one tool call at a time.

- `GET /computers/{computer_id}/work` lists a computer's records, newest first, up to 1,000 a page.
- `GET /computers/{computer_id}/work/{work_id}` reads one.
- `POST /computers/{computer_id}/work/{work_id}` with `{ "metadata" }` changes its labels. A string sets a key, `null` deletes it, and a key left out stays. A record holds up to 16 keys.
- `GET /computers/{computer_id}/work/stats` says how busy the computer is: `depth` (records that are `queued`), `pending` (records that are `starting`), `oldest_queued_at`, and `runners_polling`, the runners that polled in the last 30 seconds.

### Stop one task's work

`POST /computers/{computer_id}/work/{work_id}/stop` stops one task's work on the computer. Other tasks on the computer keep running.

- Without `force`, the calls the computer already started finish, and the record reads `stopping` until they do.
- With `{ "force": true }`, every open call ends now. A call that had not started ends as `cancelled`. A call that had started ends as `outcome_unknown`, and the record reads `stopped`.

A started call with an unknown outcome holds the Linux computer for review, as any unknown outcome does. Stopping a record that is `stopped` answers it as it is.

## Archive and delete

- **Archive** a computer with `POST /computers/{computer_id}/archive`. It is one way. The Linux computer is stopped, its disk is kept, and its slot is freed so you can make another. A Mac's credentials are revoked, so it takes no new work, and pairing it again makes a new Mac. Archive is `409` with `error_code` `computer_busy` while a task has open work on the computer.
- **Delete** a computer with `DELETE /computers/{computer_id}`. You do not need to archive it first. The machine is terminated or the Mac's credentials are revoked, and the record is hidden for good, though the calls that ran on it still name it. Delete is `409` with `computer_busy` when any task's work ran on the computer. Archive it instead.
- **Change** a computer with `POST /computers/{computer_id}`: its `name`, `description`, `metadata` and, on the Linux computer, `packages`. An archived computer cannot change: that is `400` with `error_code` `computer_archived`.

## Limits

| What | Limit |
| --- | --- |
| Active Linux computers in a workspace | 1 |
| Name | 256 characters |
| Description | 2,048 characters |
| Packages for each manager | 100 |
| Work records in one page | 1,000 |
| Labels on a work record | 16 |
| Idle time before the Linux computer stops | 15 minutes |

## Next steps

- [Tasks](/concepts/tasks): how a task shares a computer with the others in its workspace.
- [Files](/concepts/files): how a file you upload reaches a task's folder on the computer.
- [Approvals](/concepts/approvals): how a step on a Mac asks, and its deadline.