---
title: 'limits'
description: 'Read the concurrency limits of a running agent installation, release a slot whose release got lost, and override a limit capacity or max hold'
position: 28
---

# stackbone limits

> `stackbone limits` targets a **running agent installation**. With no
> `--agent` it runs against the local-dev installation linked to the current
> project, so `stackbone dev` must be running. See
> [target resolution](/docs/cli/reference/conventions#target-resolution).
> Every verb accepts `--json` and emits the
> [standard envelope](/docs/cli/reference/conventions#json-output).

Read and operate the **concurrency limits** your workspace declares under
`limits` in `stackbone.config.ts`. A limit caps how many slots can be busy at
once, and workflows take and give back slots with `acquireSlot` and
`releaseSlot`. See [Concurrency limits](/docs/sdk/workflows/concurrency-limits)
for the model. The **Limits** screen in Studio shows the same data and offers
the same actions.

| Command                                                                            | Purpose                                                      |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [`stackbone limits list`](#stackbone-limits-list)                                  | List every limit with its capacity, busy and waiting counts. |
| [`stackbone limits slots <name>`](#stackbone-limits-slots)                         | List the slots of one limit: busy first, then the queue.     |
| [`stackbone limits release <slotId>`](#stackbone-limits-release)                   | Give a busy slot back, so the next run in the queue gets it. |
| [`stackbone limits capacity <name> <n\|reset>`](#stackbone-limits-capacity)        | Override the declared capacity, or clear the override.       |
| [`stackbone limits max-hold <name> <duration\|reset>`](#stackbone-limits-max-hold) | Override the declared `maxHold`, or clear the override.      |

Every verb takes one flag:

| Flag      | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `--agent` | string | Installation id to target. Defaults to the local-dev install. |

## stackbone limits list

List every limit: busy slots over the capacity, the number of runs waiting,
and the max hold. A capacity or max hold set in Studio or with the CLI shows as an
override next to the declared value.

```text
voice-calls  18/20 busy  0 waiting  maxHold 45m
partner-api  5/8 (override; declared 5) busy  3 waiting  maxHold 20m (override; declared 10m)
```

## stackbone limits slots

`stackbone limits slots <name>`

List the slots of one limit. Each line is the slot id, its state, the run that
took it, and its label. Held and granted slots come first, then the waiting
runs in queue order.

| State     | Meaning                                                                |
| --------- | ---------------------------------------------------------------------- |
| `held`    | A run holds the slot. It stays busy until `releaseSlot` or `maxHold`.  |
| `granted` | The box gave the slot to a waiting run, and the run has not confirmed. |
| `waiting` | The run is in the queue for a slot.                                    |

```text
voice-calls  2/2 busy  1 waiting  maxHold 45m
6c1f0e1a-7d4b-4b8e-9a51-2f3c4d5e6f70  held     4c8d2e17-9a0b-4f3c-8e6d-7b5a1c2d3e4f  call-1
a90b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d  held     7f1e2d3c-4b5a-4c6d-9e8f-0a1b2c3d4e5f  call-2
0d9e8f7a-6b5c-4d3e-8f2a-1b0c9d8e7f6a  waiting  2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d  call-3
```

## stackbone limits release

`stackbone limits release <slotId> --yes`

Give a busy slot back. The oldest waiting run gets it at once. Use it when the
release got lost: the work the slot guarded ended, and no workflow called
`releaseSlot`. Otherwise the box frees the slot on its own when `maxHold`
passes.

The verb asks for `--yes`, because the run that holds the slot may still be
using it. It is idempotent: a slot that is not busy (already released, or still
waiting) prints a note and changes nothing.

```sh
stackbone limits release 6c1f0e1a-7d4b-4b8e-9a51-2f3c4d5e6f70 --yes
```

## stackbone limits capacity

`stackbone limits capacity <name> <n|reset>`

Set the capacity the box enforces over the value in `stackbone.config.ts`, or
pass `reset` to go back to it. The value is a whole number of at least 1.

```sh
stackbone limits capacity voice-calls 30      # waiting runs get the new slots at once
stackbone limits capacity voice-calls reset   # back to the declared capacity
```

Lowering the capacity takes no slot back. Busy slots stay busy, and the box
hands out new ones only when the busy count drops below the new value.

## stackbone limits max-hold

`stackbone limits max-hold <name> <duration|reset>`

Set how long one slot may stay busy over the `maxHold` in
`stackbone.config.ts`, or pass `reset` to go back to it. The value takes the
same forms as `maxHold`: `45m`, `2h`, `90s`, `500ms`, or plain digits as
milliseconds, up to 30 days.

```sh
stackbone limits max-hold voice-calls 2h      # slots granted from now on get 2h
stackbone limits max-hold voice-calls reset   # back to the declared maxHold
```

The new value applies only to slots granted after the change. A slot that is
already granted or held keeps the expiry it got when it was granted: lowering
the max hold takes back no running work, and raising it does not extend a busy
slot.