Get started
Moving from Claude Managed Agents
Move a program written for Claude Managed Agents to Little Worker by renaming its nouns, dropping what it no longer manages, and adjusting for what works differently.
Updated View as Markdown
The Little Worker API follows the shape of Claude Managed Agents, with Little Worker's words for things. A program written for Managed Agents mostly moves by renaming. This page lists the renames, what the program no longer has to do, and the places where this API behaves differently.
Step 1: Point it at Little Worker
Change the address and the headers first:
| What | In Little Worker |
|---|---|
| Base URL | https://core.thelittleworker.com/api/v1 |
| API key | Make one on the web in Settings, then API Keys. It starts with lw_key_. Send it in x-api-key, or as Authorization: Bearer. API keys has the steps. |
| Version | Little-Worker-Version: 2026-10-19 on every request. Without it, or with any other value, the answer is 400. Little Worker serves one dated version at a time. |
| Beta flags | Little-Worker-Beta. None are offered today, and any value is 400. |
| Workspace | Little-Worker-Workspace-Id is optional. It must name the key's own workspace, or the answer is 403. |
| Rate limit headers | little-worker-ratelimit-requests-limit, -remaining and -reset on every answer except the OpenAPI document. |
| Request id | The request-id header, and request_id in an error. |
Where a header carries anthropic- for Claude, it carries Little-Worker- or little-worker- here.
The whole API is described by an OpenAPI document at https://core.thelittleworker.com/api/v1/openapi.json, which needs no key.
Step 2: Rename the nouns
Rename in path segments, JSON keys, type values, event names and the prefixes of ids. Everything else is kept as Claude spells it: field names, enum values, status codes and HTTP verbs. What you put in metadata, in a tool's input_schema, in a tool's input and output, and in content blocks is yours, and is not renamed.
| Claude Managed Agents | Little Worker | Id prefix |
|---|---|---|
| agent | worker | agent_ becomes worker_ |
| session | task | sesn_ becomes task_ |
| environment | computer | env_ becomes computer_ |
| vault | password set | vlt_ becomes password_set_ |
| credential | password | vcrd_ becomes password_ |
| deployment | routine | depl_ becomes routine_ |
MCP server (mcp_servers, mcp_toolset) |
app (apps, app_toolset) |
none |
| tool confirmation | approval | none |
| memory store, memory, file, skill | the same words | unchanged |
The same rename applies to events and to the other routes:
| Claude | Little Worker |
|---|---|
agent.* events |
worker.* events |
session.status_* events |
task.status_* events |
session.usage |
task.usage |
session.thread_* events |
task.thread_* events |
user.tool_confirmation |
user.approval, with the same tool_use_id, result and deny_message fields |
agent_toolset_20260401 |
worker_toolset_20260401 |
agent_with_overrides |
worker_with_overrides |
event ids with sevt_ |
event ids with event_ |
/sessions/{id}/events |
/tasks/{task_id}/events |
/sessions/{id}/events/stream |
/tasks/{task_id}/events/stream |
/vaults/{id}/credentials |
/password_sets/{password_set_id}/passwords |
/deployments |
/routines |
Ids differ in shape as well as prefix. A task id is task_ and 26 letters and digits, and most other ids are their prefix and 32 hexadecimal characters. A program that checks the shape of an id needs the new rule.
Creating a task is where most renames land:
| In a session create | In POST /tasks |
|---|---|
agent |
worker: a worker id, or { "type": "worker", "id", "version" } to pin a version |
environment_id |
computer_id, which is optional |
vault_ids |
password_set_ids |
title, metadata, resources |
the same names |
POST /tasks also takes initial_events, budget and chat_id.
Step 3: Stop managing these
Little Worker does these for you, so a program can drop the code that did them:
| A program for Managed Agents | In Little Worker |
|---|---|
| Starts a program on its own host to poll for work, and holds a key for it | Nothing to start. The Linux computer's runner is Little Worker's, and the Mac app runs its own. |
| Names an environment on every session | computer_id is optional. A workspace has at most one Linux computer, shared by its tasks, and the Macs its people paired. |
| Starts and stops the sandbox | Core stops the Linux computer after 15 idle minutes, and starts it again when a task needs it. |
| Passes vault ids on every session | Left out, a task signs in with the worker's own password set, then the workspace's shared one. |
| Lists memory stores on every session | Left out, a task reads the stores attached to its worker, and the worker's own store is always read. |
| Picks a model for every agent | A worker without a model follows its Quality (fast, standard or best). Every read answers the model that Quality picks now. |
| Writes a title for every session | Left out, a task's title is the first words of its first message. |
| Builds a screen to answer tool confirmations | A person can answer every approval in the app. A key answers only if it was made with Can allow actions. |
Step 4: What works differently
Requests and answers
| Here | What to change |
|---|---|
An error carries retryable and error.details.error_code beside type and message. |
Read error_code for the exact reason, and retryable before you retry. |
A list answers { "data": [...], "next_page": ... }, with limit from 1 to 100 (1,000 on computers, work records and routine runs), 20 when left out. The task list also answers prev_page. |
Page with next_page. |
Idempotency-Key works on POST /tasks, POST /tasks/{task_id}/events, and the routes that make or change workers and routines. Every other route ignores it. |
Before you retry another create, list the objects and look for the one you made. |
| A workspace may make 1,200 reads and 300 writes a minute across all its keys, and hold 10 open event streams. | Count requests for the whole workspace, not for one key. |
Tasks and events
| Here | What to change |
|---|---|
A worker works on one task at a time. The worker's other tasks wait in the order given, as status: running with state.waiting_reason: busy. A worker holds up to 20 waiting runs, and the next message is 429 with error_code queue_limit and retryable: true. |
Do not start many tasks on one worker and expect them side by side. Send again when the worker has caught up. |
Every task has a budget: the most its work may cost at list price. Left out it is $5.00 ("500", in whole US cents) and the most is $1,000.00. budget: null is 400 with budget_required. |
Set budget on tasks that need more. A task that spends its budget stops with budget_reached. Raise budget with POST /tasks/{task_id} and it goes on. |
status is running, idle, rescheduling or terminated, and state says the same in four words (not_started, working, needs_you, done). No task is terminated yet. A plan or spending cap holds a task as rescheduling, and it goes on by itself. |
Read state when you need to know whether the work is done or waits for you. |
Two stop reasons are Little Worker's own: turn_limit after 200 model turns in a run, and time_limit after 2 hours of work in a run. The work is kept. |
Send a message, or send the task back, to start a fresh run. |
user.accept and user.send_back are Little Worker's events, and each is sent alone. A plain user.message to a done task reopens it as a send back does. |
Use user.send_back to ask for changes. |
A stream with no cursor sends only events written after it opens. after, or Last-Event-ID, resumes after a sequence, and after=0 replays every kept event. A message sent while the worker is busy is listed where it was accepted. |
Open the stream with after=0 to see the whole task. Follow a task as it works shows how to reconnect. |
sequence counts the events of the whole chat, so one task's events skip numbers. |
Use the last sequence you saw as the cursor, and do not expect a gap-free count. |
A task shows usage and stats, and Little Worker adds charged, included and own_key_calls to usage. GET /tasks/{task_id}/receipts lists what each run cost. |
Read receipts when you need what the workspace paid. |
POST /tasks/{task_id}/withdraw takes a task back. Reading it afterwards answers 404. |
Use an interrupt, then archive, when you want to keep the task. Stop work and keep history has both. |
Workers
| Here | What to change |
|---|---|
A worker has extra fields: title, rules, quality, model_source, status and revision_id. |
Ignore the ones you do not use. |
A worker without a tools list reads and runs every tool group as always_allow. In a worker_toolset_20260401 you send, each entry of configs is a tool group, such as computer or memories, not a single tool, and a group that changes things asks unless you set it otherwise. |
Set permission_policy for each group you care about. |
A step that sends, pays, posts, deletes, changes settings or uses a password for the first time asks a person, whatever its policy says. Its worker.tool_use carries evaluation.type fixed_rule. |
Treat an evaluation.type you do not know as a plain ask. |
A worker's networking is limited with no hosts unless you name some, so it reaches no website. A site entry such as example.com covers its subdomains. unrestricted needs a key made with Can allow actions. |
Name the sites a worker needs. |
execution_identity is always { "type": "service_account" }. aws_role is 400: "aws_role is not offered." |
Remove aws_role. |
Archiving a worker is 409 with conflict_error while it has a queued, running or waiting run. |
Interrupt or take back its tasks, wait for them to stop, then archive. |
Approvals, passwords and files
| Here | What to change |
|---|---|
A key answers an approval only if it was made with Can allow actions, or the answer is 403 with person_required. A worker's first use of a saved password, an email it sends, a press in its browser, a public post and a refund are answered only by a person, in the app. |
Make a key for the program with the switch on, and leave those steps to a person. Answer approvals from your program shows how. |
A password's secret_value is 8 to 4,096 characters. Each password has a permission: ask waits for a person on its first use in a task, and always does not. A password set holds up to 256 passwords. A value goes in and never comes out. |
Check the length of values you save. |
An uploaded file can be downloaded, and every file shows downloadable: true. POST /files/{file_id}/keep keeps a file a task made after the task's history is deleted. |
Use keep for files you need to outlive their task. |
| Deleting a task needs a key made with Can delete tasks. Settings does not offer that switch yet. | Archive the task instead. |
Computers
| Here | What to change |
|---|---|
A computer's config.type is cloud for the workspace's Linux computer, or self_hosted for a Mac a person paired in the Mac app. POST /computers with self_hosted is 400. A second cloud computer is 409 until you archive the first. |
Pair a Mac in the app, and do not create one through the API. |
Every task shares the computer's files. A task's skills and memory are folders under .little-worker/tasks/<task_id>/ in the workspace, which the Linux computer makes when the task first uses it. A Mac does not make them yet. |
Read a task's own folder, not a shared path. |
Archiving a computer while a task's work is on it is 409 with computer_busy. |
Wait for the work to end, then archive. |
Routines, webhooks and history
| Here | What to change |
|---|---|
A routine runs at least 5 minutes apart, and a tighter schedule is 400. A subscription may require a longer gap and allow fewer routines. A workspace holds up to 1,000 routines and a worker up to 50. Little Worker adds triggers, which start a routine from a webhook, an email or an app event. |
Check a subscription's routine limits before you make many. |
| Webhooks are added in Settings, not through the API. A notice is posted up to 5 times, and Settings offers the notices for a task starting to work and stopping. A notice names the task and carries no task data. | Read the task with your key when a notice arrives. Webhooks shows how. |
On the free subscription, task history older than 7 days is deleted. The task stays readable, and its events start with a history.purged event. A cursor from before it is 400 with cursor_expired. A paid subscription keeps history until you delete it. |
Keep your own copy of events you need for longer. |
Step 5: What is not here
- Webhook routes. Webhooks are added in Settings.
- Self-hosted computers made through the API, and
aws_rolefor a worker. Both are400, as above. - Beta flags.
Little-Worker-Betatakes none today. - A route to call a model directly. The API covers what its OpenAPI document lists: workers, tasks and their events, approvals, routines, apps, computers, files, skills, memory stores, password sets, models, tunnels, telemetry destinations and dreams.
Next steps
- Overview: the main ideas, headers, errors and limits in one place.
- Quickstart: make a worker and give it a task from your own code.
- Tasks: states, stop reasons, budgets and limits in one place.
- Tasks reference: every field of a task, and the routes to give, list, read and change tasks.
- Events reference and Approvals reference: the routes a ported program calls most.