Concepts

Apps

An app is a service a person connected, with the tools a worker may use in it and what it may do there.

Updated October 25, 2026

An app is a service that a person connected to Little Worker, such as a mail, calendar or tracker service. Once it is connected, a worker can use the app's tools: read a calendar, file an issue, send a note. An app is an MCP server in Claude Managed Agents.

The app itself belongs to the person. They sign in to it and set how much workers may do in it, in the app. The API lets you list the apps, install one by its address, and choose which apps a worker uses. This page explains what an app holds, what Read and Act mean, how a worker gets an app, and how to reach an app on a private network.

What an app holds

GET /apps lists the apps a person connected. It shows nothing of an app's sign-in.

Field	What it is
`id`	The app's id: `app_` and a number, such as `app_12`.
`name`	The app's name.
`url`	The address of the app's server, without any query, which may carry a key. It is the address a worker's `apps` entry names.
`connected`	`true` when the person signed in to the app.
`read`	`on` or `off`.
`act`	`allow`, `ask` or `off`.

POST /apps with a name (1 to 80 characters) and a url (up to 2,048 characters) installs an app by its address and answers it. The address must pass the same rule Little Worker applies whenever it calls an app: HTTPS, a public address, and no credentials in it. An address that is already installed answers that app. Signing in to an app, and changing its Read and Act, are the person's, in the app.

Read and Act

Every app has two levels. They are the workspace's ceiling for that app.

Level	Values	What they do
`read`	`on` or `off`	Whether the app's tools that only read may run.
`act`	`allow`, `ask` or `off`	What happens to a tool that changes something. `allow` runs it, `ask` waits for an Allow, and `off` refuses it.

A worker's settings can narrow these levels but never widen them. And some steps ask whatever the levels say: a step that sends, pays, posts or deletes always asks. See Approvals.

How a worker gets an app

A worker uses only the apps it names. A new app reaches no worker until a person chooses the worker for it on the Apps page, or you name the app on the worker.

A worker names its apps in apps, up to 20. Each is { "type": "url", "name", "url" }, and each name is used once. Each url must match an app installed in the workspace, or the answer is 400 naming the app.

Each app in apps needs one entry in the worker's tools: its app toolset, { "type": "app_toolset", "app_name", "default_config", "configs" }. An app without a toolset, or a toolset without an app, is 400 naming the app, and an app has at most one toolset.

app_name is the name of the app in apps.
default_config covers every tool of the app that configs does not list. It is { "enabled", "permission_policy": { "type" } }. Left out, the tools are on and always_ask.
configs lists single tools by their own name, each with enabled and a permission_policy.

permission_policy.type is one of three values:

`permission_policy.type`	What it does
`always_allow`	Runs the step.
`always_ask`	Waits for an Allow, even for a tool that only reads.
`auto`	Lets a tool that only reads run, and sends every other step to a safety check. The check runs what it allows, refuses what it blocks, and asks when it is unsure, slow (3 seconds) or unavailable. When the app's `act` is `ask`, `auto` asks too.

When you add an app to a worker, send its toolset in the same call. A change to tools replaces the whole list, so send the entries you want to keep as well. Both lists are part of the worker's version, and a task keeps the apps and toolsets of the worker version it started with. A change reaches the next task, not the one at work.

To give one task different apps without changing the worker, give the task a worker of { "type": "worker_with_overrides", ... } with its own apps and tools, or change them with POST /tasks/{task_id} while the task is idle. The worker does not change.

What you see when a worker uses an app

A call to an app is a pair of events in the task:

worker.mcp_tool_use has the app_name, the app's own tool name, and the input. It carries evaluated_permission and evaluation once something has decided the step.
worker.mcp_tool_result has the app's answer. mcp_tool_use_id names the call, and is_error says whether it failed.

Two task errors concern apps. app_connection_failed_error means the app could not be reached, and app_authentication_failed_error means it refused the sign-in. Both name the app in app_name and leave the task working.

Each finished run has a receipt that lists the app actions decided in it: the tool, whether it was allowed or denied, and whether a setting or a person decided it (decided_by). What the worker sent to the app never appears. See the Tasks reference.

Apps are called by Little Worker, never from a computer, so a computer's networking cannot turn them off. See Computers.

An app's sign-in is kept as a password, in a password set. See Password sets.

Apps on a private network

Some apps live on a private network and cannot be reached from the internet. A tunnel is a way in to them. Nothing opens an inbound port.

Make a tunnel with POST /tunnels, with an optional display_name. It gets an assigned domain.
Run the connector. POST /tunnels/{tunnel_id}/reveal_token answers the connector token that Cloudflare's cloudflared runs with. Run Little Worker's tunnel proxy beside cloudflared on the private network. POST /tunnels/{tunnel_id}/rotate_token makes a new token.
Give it a certificate. A tunnel takes calls only while it holds a CA certificate. POST /tunnels/{tunnel_id}/certificates takes a ca_certificate_pem of up to 8,192 bytes. A tunnel holds two at a time, and POST .../certificates/{certificate_id}/archive archives one. Little Worker trusts only the CAs registered on the tunnel.
Install the app at an address under the tunnel's domain.

An app whose address is under the tunnel's domain is reached through the tunnel and never over the public internet. Only the tasks of the workspace that owns the tunnel can reach it. GET /tunnels lists tunnels, GET /tunnels/{tunnel_id} reads one, and POST /tunnels/{tunnel_id}/archive archives one. Add include_archived=true to a list to see archived ones.

Limits

What	Limit
Apps on one worker	20, each name used once
App name when installing	1 to 80 characters
App address	2,048 characters
Toolsets for one app	1
CA certificates on a tunnel	2 at a time, each up to 8,192 bytes
Automatic check	3 seconds, then it asks

Next steps

Approvals: how an app step that asks reaches a person, and who may answer.
Password sets: where an app's sign-in is kept.
Runs and events: the worker.mcp_tool_use and worker.mcp_tool_result events in order.