> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Routine settings

Every routine setting: durability, step timeouts, retries, concurrency and paused sandboxes, with defaults, values and examples.

Most routine settings live in the definition, under `defaults`, and a step can set its own `timeout_ms` and `retry`. A run can ask for another durability when it starts. [Definitions](/routines/definitions) has the whole format.

| Setting | Default |
|---|---|
| [Durability](#durability): `defaults.durability` | `standard` ([per field](#durability)) |
| [Concurrency](#concurrency): `defaults.concurrency.limit` | none: every run starts ([per field](#concurrency)) |
| [Pause sandboxes while waiting](#pause-sandboxes-while-waiting): `defaults.pause_sandboxes` | `false` |
| [Step timeout](#step-timeout): `defaults.timeout_ms` | 30,000 ms ([per field](#step-timeout)) |
| [Retries](#retries): `defaults.retry` | none: a step runs once |

## Runs

### Durability

What a crash may lose. `ephemeral` runs in memory and journals nothing: the fastest, and a crash loses the run. `standard` commits the journal in groups, so an effect is durable before the steps that need it run. `strict` commits the intent and the result of every effect step.

- **Field:** `defaults.durability` and `durability` on [definition](/api/put-v1-routines-routine-) and [run](/api/post-v1-routines-routine-runs)
- **Default:** `standard` (`defaults.durability`, definition), the routine's `defaults.durability` (`durability`, run)
- **Values:** `ephemeral`, `standard` or `strict`
- **Invalid value:** [`422 routine_invalid`](/errors#routine_invalid), [`400 invalid_request`](/errors#invalid_request)
- **Guide:** [Durability](/routines#durability)

```json
{"defaults": {"durability": "strict"}}
```

### Concurrency

At most `limit` runs active per `group`. A new run in a full group waits (`queue`), ends canceled (`skip`), or cancels the oldest active run first (`cancel_running`).

- **Field:** `defaults.concurrency.limit` and `defaults.concurrency.on_limit` on [definition](/api/put-v1-routines-routine-)
- **Default:** none: every run starts (`defaults.concurrency.limit`), `queue` (`defaults.concurrency.on_limit`)
- **Values:** 1 to 1,000 (`defaults.concurrency.limit`); `queue`, `skip` or `cancel_running` (`defaults.concurrency.on_limit`)
- **Invalid value:** [`422 routine_invalid`](/errors#routine_invalid)
- **Guide:** [Concurrency](/routines/definitions#concurrency)

```json
{"defaults": {"concurrency": {"limit": 1, "group": "${{ inputs.customer_id }}", "on_limit": "queue"}}}
```

### Pause sandboxes while waiting

Pauses the sandboxes a run execs in while it waits long and nothing else of it runs, so they bill no CPU; the next exec or the end of the run resumes them. Anything else using those sandboxes freezes meanwhile, so set it only for sandboxes the routine's runs have to themselves. Needs `sandboxes:write` on the publishing key.

- **Field:** `defaults.pause_sandboxes` on [definition](/api/put-v1-routines-routine-)
- **Default:** `false`
- **Values:** `true` or `false`
- **Invalid value:** [`422 routine_invalid`](/errors#routine_invalid)

```json
{"defaults": {"pause_sandboxes": true}}
```

## Steps

### Step timeout

How long one attempt of a `uses` step may take, or a whole `map` step. A step's own `timeout_ms` wins over `defaults.timeout_ms`. A job step such as `render/video@1` that sets neither gets its operation's timeout, one hour. Wait and sleep steps are not affected.

- **Field:** `defaults.timeout_ms` and `steps[].timeout_ms` on [definition](/api/put-v1-routines-routine-)
- **Default:** 30,000 ms (`defaults.timeout_ms`), `defaults.timeout_ms` (`steps[].timeout_ms`)
- **Values:** 1 to 86,400,000 ms
- **Invalid value:** [`422 routine_invalid`](/errors#routine_invalid)
- **Guide:** [Steps](/routines/definitions#steps)

```json
{"defaults": {"timeout_ms": 120000}}
```

### Retries

How often a failed step runs again, and how long it waits between attempts. `defaults.retry` applies only to `pure` and `read` steps; a `write` step retries only with its own `retry`, and an `irreversible` one never. Only failures the callee marks retryable are retried, and every attempt carries the same idempotency key.

- **Field:** `defaults.retry` on [definition](/api/put-v1-routines-routine-)
- **Default:** none: a step runs once
- **Values:** `max_attempts`: 1 to 20; `initial_ms`: 1 to 3,600,000 (default 200); `factor`: 1 to 10 (default 2); `max_ms`: 1 to 86,400,000 (default 30,000); `jitter`: `true` or `false` (default `true`)
- **Invalid value:** [`422 routine_invalid`](/errors#routine_invalid)
- **Guide:** [Retries](/routines/definitions#retries)

```json
{"defaults": {"retry": {"max_attempts": 3, "initial_ms": 500}}}
```

## Fixed in the beta

These work one way in the beta, and no request field changes them.

### When sandboxes pause

**After 30 seconds of waiting.** With `pause_sandboxes`, a run's sandboxes pause once it waits at least 30 seconds (a wait, a sleep, or a signal wait with no deadline).

### Lookahead

**On.** While a step that waits on I/O runs, the node creates the sandbox the next `sandboxes/exec@1` step needs. A pre-warmed sandbox whose step does not run is deleted after 30 seconds, and that time bills.

### Run history

**Kept 30 days.** Runs, their steps and their events are kept 30 days.