Computers

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.

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.

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 [email protected], 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:

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

Next steps

• Tasks: how a task shares a computer with the others in its workspace.
• Files: how a file you upload reaches a task's folder on the computer.
• Approvals: how a step on a Mac asks, and its deadline.