> For the complete documentation index, see [llms.txt](/llms.txt). > A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt). --- title: Worker sizes description: Choose how much CPU and memory your managed workers get, set it on a project or an environment, and fix workers that run out of memory. last_verified: 2026-11-09 --- A **worker size** sets how much CPU and memory each managed worker gets, such as 1 vCPU and 1 GB for Small 2x. You set a size on an [environment](/docs/run/environments.md), or a default on the project that every environment without a size of its own inherits. You never set it on a single deploy, so deploying, promoting, or rolling back never changes how big your workers are. Choose a larger size when a tool needs more memory than its worker has. An incident agent whose `search_logs` tool loads 1.5 GB of logs into memory is killed every time it searches on a 1 GB worker; on a 2 GB worker, the same search completes. Choose a smaller size for an agent that mostly waits on model and API calls. Sizes apply only to workers AGNT5 runs for you. Environments whose workers run on your own infrastructure, shown in Studio as **Customer-hosted**, and [serverless endpoints](/docs/run/serverless-endpoints.md) have no size. --- ## Sizes on offer List the sizes you can choose, with the CPU and memory each worker gets: ```bash agnt5 worker-size list ``` ```text NAME SIZE VCPU MEMORY micro Micro 0.25 0.25 GB small-1x Small 1x 0.5 0.5 GB small-2x Small 2x (default) 1 1 GB medium-1x Medium 1x 1 2 GB medium-2x Medium 2x 2 4 GB Set one: agnt5 worker-size set --env ``` AGNT5 can add and retire sizes, so the CLI and Studio always read the current list from the server; this output is the list at launch. Commands take the value in the **NAME** column. Memory is in GB of 1024 MiB. - **Memory is a hard ceiling.** A worker that uses more memory than its size is stopped, with everything running on it. See [When a worker runs out of memory](#when-a-worker-runs-out-of-memory). - **CPU can burst.** A worker always gets its size's vCPU. When the machine has spare capacity, it can use up to its size or 2 vCPU, whichever is larger, which keeps startup quick on small sizes. When AGNT5 retires a size, environments already on it keep it, and the CLI and Studio mark it as no longer offered. Once an environment moves to another size, it can't choose the retired one again. --- ## How an environment's size is chosen At each deploy, AGNT5 chooses the size for the environment's workers in this order: 1. The environment's own size, if you set one. 2. The project's default, if you set one. 3. The size the environment last deployed at. An environment that was deployed before worker sizes existed keeps the CPU and memory it had, with up to 1 GB of memory, until you set a size. 4. For an environment that has never been deployed, AGNT5's default size, marked `(default)` in the list. The deployment stores a copy of that size's CPU and memory, so its workers keep them even if AGNT5 later edits or retires the size. | Action | Size the workers get | | --- | --- | | Deploy or [promote](/docs/run/environments.md#promote-a-deployment) | The target environment's size. A build verified in preview at Small 2x runs at production's Medium 2x once promoted | | [Roll back](/docs/run/environments.md#roll-back) | The environment's current size | | Run an [experiment](/docs/improve/experiments.md) against a deployment | That deployment's size | | Change a size | The new size, replacing the workers running now. See [What a resize does to running work](#what-a-resize-does-to-running-work) | --- ## Change a size Changing a size needs the developer role or above in the project. > Changing the size of an environment that has a deployment replaces its running workers. A tool call or workflow step that is still running may run again on a new worker. Read [What a resize does to running work](#what-a-resize-does-to-running-work) before you resize an environment that serves traffic. ### From the CLI `agnt5 worker-size` reads the project from the current directory; pass `--project ` to name another. If the command isn't found, [update the CLI](/docs/cli/install.md#upgrade). Sign in with `agnt5 auth login` or use a personal API key: service keys can't change sizes. See the project default and each environment's size, with where it comes from: ```bash agnt5 worker-size show ``` For a project whose default is Small 2x, with production set to Medium 1x, the output looks like this: ```text Project default: Small 2x (1 vCPU, 1 GB) ENVIRONMENT SIZE SET ON preview Small 2x (1 vCPU, 1 GB) project default staging Small 2x (1 vCPU, 1 GB) project default production Medium 1x (1 vCPU, 2 GB) environment ``` Set one environment's size with `--env`, or the project default without it: ```bash agnt5 worker-size set medium-1x --env production # production only agnt5 worker-size set small-2x # the project default ``` Before it changes anything, the command lists what the change reaches and asks you to confirm. For a project default, that's every environment that inherits it and whether its running workers are replaced. After the change, it prints an `agnt5 deploy status --watch` command to follow the new workers starting. Clear a size to go back to the next one in the order: ```bash agnt5 worker-size clear --env production # production inherits the project default again agnt5 worker-size clear # remove the project default ``` Clearing an environment's size moves it to the project default, and replaces its workers if that's a different size. With no project default, the environment keeps the size it runs at and nothing restarts. Clearing the project default restarts nothing: the environments that inherited it keep the size they run at. In scripts and CI, pass `--yes` to skip the confirmation, and `--output json` for machine-readable output. Without a terminal and without `--yes`, `set` and `clear` refuse rather than change sizes nobody confirmed. ### From Studio 1. Open your project and go to **Settings** → **Environments**. The **Worker size** column shows each environment's own size. **Not set** means the environment uses the project default, or the size it already runs at. 2. In the environment's row actions, choose **Change size**. 3. Pick a size. Studio tells you whether the environment's running workers will be replaced. 4. Choose **Change size** to confirm. Studio sets one environment's size at a time. To set or clear the project default, use `agnt5 worker-size set` or `agnt5 worker-size clear` without `--env`. ### Check the size a deployment runs at `agnt5 deploy status ` and `agnt5 deployment status` print the deployment's stored size on a `Size:` line, such as `Size: medium-1x (1 vCPU, 2 GB)`. In Studio, the **Deployments** table has a **Size** column, and a deployment's page shows **rolling out** next to its size while new workers replace old ones. --- ## What a resize does to running work When an environment's size changes, AGNT5 starts workers at the new size beside the old ones. The old workers keep serving until the new ones are ready. Then they stop taking new work and get a few seconds to finish what they're running. Work that finishes in that time is recorded as usual. A run that's still in progress resumes on a new worker within seconds, from its last recorded step. The work that was cut off when the old worker stopped can run again: - **A workflow step** runs again from the start on the new worker. Steps that already completed don't run again. - **A tool call** with the Python SDK's default `recovery_policy="unknown_outcome"` isn't run again automatically. AGNT5 records that it can't tell whether the call took effect, and the agent receives the call as failed. The run can still complete, and the model may call the tool again. A tool with `recovery_policy="idempotent_retry"` is run again by AGNT5. If the incident agent was partway through `create_incident` when its worker stopped, the incident may already exist when the model calls `create_incident` again. Make tools and steps with outside effects safe to repeat, for example by sending an idempotency key to the incident service, and resize at a quiet time when you can. [Tools](/docs/build/tools.md) describes `recovery_policy`, and [Workflows](/docs/build/workflows.md) shows how to pass a step's idempotency key to another service. Changing the project default does this in every environment that inherits it. An environment with nothing deployed has no workers to replace; its next deploy starts at the new size. --- ## When a worker runs out of memory **Symptom:** a run fails with `WORKER_OOM_KILLED`, "worker was OOM-killed during this run and retry budget was exhausted". The deployment may also be reported unhealthy, with workers stopped as `OOMKilled`. **Cause:** the worker used more memory than its size allows, so it was stopped, along with everything running on it. AGNT5 puts the interrupted run back in the queue and tries again. A run that keeps running out of memory fails after a few attempts, usually within a minute, instead of retrying forever. A tool call that was running is settled as it is [during a resize](#what-a-resize-does-to-running-work). A few side effects to expect: - Other runs on the same worker are interrupted too, and can fail with `WORKER_OOM_KILLED` even if they used little memory. - Some out-of-memory stops are reported as `WORKER_TERMINATED`, "worker terminated (Error)", instead. If a memory-heavy run fails that way, treat it as out of memory. - An environment that runs a single worker can be left with no running worker for a few minutes after repeated stops, while restarts back off. **Fix:** 1. Check the environment's current size with `agnt5 worker-size show`. 2. Choose a size with more memory than the run needs from `agnt5 worker-size list`. 3. Set it, for example `agnt5 worker-size set medium-1x --env production`. 4. When the new workers are ready, start the failed runs again. AGNT5 doesn't restart a run that has failed. A larger CPU allowance doesn't help here: a worker at its CPU limit slows down, while one over its memory limit is stopped. If you'd rather keep the size, lower what the tool holds in memory at once, for example by searching logs in pages instead of loading them all. --- ## When a size change is refused AGNT5 checks every size change, and every deploy, against your project's quota before anything changes. The quota comes from your plan and covers the workers of all the project's environments. Each environment counts at its maximum workers plus one, the extra worker a rolling update starts before it stops an old one. A size that doesn't fit is refused, and nothing changes. The error names the size, the quota, and what the project would need, then suggests a fix. For a project default, the change is refused as a whole if any environment that inherits it doesn't fit. To make room: - Choose a smaller size. - Lower the environment's maximum workers with `agnt5 deploy --max-replicas`. - Stop an environment you no longer use. AGNT5 also refuses a size it no longer offers, and any size for a customer-hosted environment. The error explains which. **Model**: worker size = CPU and memory per managed worker, set on an environment or as a project default, never per deploy. Resolution at deploy: environment's own size, then project default, then the size the environment last deployed at (environments from before sizes keep their old resources, up to 1 GB memory), then AGNT5's default for never-deployed environments. Each deployment stores its size's CPU and memory. Memory is a hard ceiling; CPU is guaranteed and bursts up to max(size, 2 vCPU). The offered list can change; read it with `agnt5 worker-size list`. Customer-hosted environments and serverless endpoints have no size. **Commands**: `agnt5 worker-size list`, `agnt5 worker-size show [--project P]`, `agnt5 worker-size set [--env E] [--project P] [--yes]`, `agnt5 worker-size clear [--env E] [--project P] [--yes]`. Without `--env`, `set` and `clear` act on the project default. Needs a user login or personal API key and the developer role or above. **Resize**: new workers start before old ones stop; in-progress runs resume on a new worker from the last recorded step; an interrupted workflow step runs again; a Python tool call with the default `unknown_outcome` policy is reported to the agent as failed, and one with `idempotent_retry` runs again. **Out of memory**: run fails with `WORKER_OOM_KILLED` (sometimes `WORKER_TERMINATED`) after a few attempts; fix by setting a size with more memory. ## Next steps * [Environments](/docs/run/environments.md): promote, roll back, and scope secrets per environment. * [Tools](/docs/build/tools.md): set `recovery_policy` on tools that are safe to run again. * [Deploy commands](/docs/cli/deploy.md): replicas, deployment status, and deploy errors.