# State stores (beta)

A state store is a small, named key-value store that belongs to your organisation. Use one for the live state an experiment shares while it runs: the best score so far, a counter, a lock, a config value. Every key holds a JSON value and a version number. Conditional writes protect against concurrent updates while the key and store remain in place; deleting and recreating either resets versions and requires separate coordination.

Stores are for coordination, not bulk data. Keep large inputs and outputs in [datasets](https://docs.cthree.cloud/datasets.md) and [artifacts](https://docs.cthree.cloud/artifacts.md), and put a pointer to them in a store if other processes need to find them.

## Get access[​](#get-access "Direct link to Get access")

State stores are in beta. Accounts must be approved before they, or any API key they own, can use them. [Ask for access](https://cthree.cloud/beta). Until your account is approved, every command returns `STATE_ACCESS_REQUIRED`:

```
Error: STATE_ACCESS_REQUIRED — State stores are in beta. Ask C3 for access.
```

## Commands[​](#commands "Direct link to Commands")

```
c3 state create <store> [--json]
c3 state ls [--json]
c3 state show <store> [--json]
c3 state rm <store> [--yes] [--json]
c3 state keys <store> [--prefix P] [--limit N] [--all] [--json]
c3 state get <store> <key> [--json]
c3 state put <store> <key> <value|-> [--string] [--if-version N | --if-absent] [--json]
c3 state del <store> <key> [--if-version N] [--json]
```

`c3 state <subcommand> --help` prints the details and examples for each one.

### Stores[​](#stores "Direct link to Stores")

```
c3 state create exp-42       # names: 1-64 lowercase letters, digits, . _ or -
c3 state ls                  # every store in your organisation
c3 state show exp-42         # key count and size against the limits
c3 state rm exp-42           # asks first; --yes for scripts
```

```
NAME     KEYS  SIZE    LAST WRITE            CREATED BY
exp-42   3     1.2 KB  2026-11-19 14:05 UTC  auth0|alice
```

Everyone approved in your organisation sees the same stores. Deleting a store removes every key in it and cannot be undone; a new store with the same name starts empty.

### Keys[​](#keys "Direct link to Keys")

```
c3 state put exp-42 best '{"score": 0.91}'       # any JSON value
c3 state put exp-42 status running --string      # store plain text
cat config.json | c3 state put exp-42 config -   # read the value from stdin
c3 state get exp-42 best                         # prints only the value
c3 state get exp-42 best --json                  # value, version, updated_at, updated_by
c3 state keys exp-42 --prefix worker/ --all      # list keys
c3 state del exp-42 lock
```

`c3 state get` prints the value and nothing else, so it pipes straight into other tools: `c3 state get exp-42 best | jq .score`. Keys can contain `/` and are listed in key order.

## Conditional writes[​](#conditional-writes "Direct link to Conditional writes")

A new key starts at version 1; every update increases its version by one. Two flags make a write conditional, and a failed condition writes nothing:

| Flag             | Writes only if                |
| ---------------- | ----------------------------- |
| `--if-version N` | the key is still at version N |
| `--if-absent`    | the key does not exist yet    |

```
$ c3 state put exp-42 best '{"score": 0.93}' --if-version 4
Error: STATE_CONFLICT — exp-42/best is at version 5, not 4
```

Every error exits with status 1 and starts with the error code, so scripts can branch on the code in the message.

Deleting and recreating a key resets its version to 1. Deleting and recreating a store also starts all keys afresh. Versions do not identify a key or store across recreation: if Alice reads score 0.91 at version 1, Bob deletes and recreates it with score 0.99 at version 1, Alice's stale `--if-version 1` write of 0.93 succeeds. A stale conditional delete can likewise remove the replacement key.

The lock, best-score and counter examples below require that no other process deletes and recreates the key or store during the operation. Coordinate deletion separately. Version checks alone do not prove lock ownership across recreation; keep lock deletion under the owner's control and prevent store recreation while workers are using it.

### A lock[​](#a-lock "Direct link to A lock")

Only one process gets the lock; the others see `STATE_CONFLICT` and move on.

```
if c3 state put exp-42 lock "$HOSTNAME" --string --if-absent; then
  run_exclusive_step
  c3 state del exp-42 lock
fi
```

### Keep the best score[​](#keep-the-best-score "Direct link to Keep the best score")

Read the current version, then write only if nobody changed it in between. On a conflict, read again and retry.

```
while :; do
  current=$(c3 state get exp-42 best --json)
  version=$(jq .version <<<"$current")
  best=$(jq .value.score <<<"$current")
  awk "BEGIN { exit !($score > $best) }" || break           # not better: done
  c3 state put exp-42 best "{\"score\": $score}" --if-version "$version" && break
done
```

### A counter[​](#a-counter "Direct link to A counter")

```
while :; do
  current=$(c3 state get exp-42 done --json)
  next=$(( $(jq .value <<<"$current") + 1 ))
  c3 state put exp-42 done "$next" --if-version "$(jq .version <<<"$current")" && break
done
```

Start the counter once with `c3 state put exp-42 done 0 --if-absent`.

## Using a store from a job[​](#using-a-store-from-a-job "Direct link to Using a store from a job")

Jobs do not receive C3 credentials, so a script running on C3 can only reach a store with an API key you supply. Create a dedicated key with `c3 apikey create`, give it to the job only for as long as you need it, and revoke it afterwards with `c3 apikey revoke`. Be aware that anything you put in the project folder is uploaded with the workspace and kept in C3 storage, and that a key printed by your script ends up in its logs. Built-in credentials for jobs are planned.

## Dashboard and coding agents[​](#dashboard-and-coding-agents "Direct link to Dashboard and coding agents")

The [State stores page](https://cthree.cloud/dashboard/state) in the dashboard does the same things, and each control shows the `c3 state` command it runs. Coding agents use the MCP tools `state_create`, `state_list`, `state_show`, `state_delete`, `state_keys`, `state_get`, `state_put` and `state_delete_key`; see [MCP server](https://docs.cthree.cloud/mcp.md#tools).

The API is `/v2/state`, with the same credentials as the CLI:

| Method and path                                                                  | CLI               |
| -------------------------------------------------------------------------------- | ----------------- |
| `POST /v2/state` with `{"name"}`                                                 | `c3 state create` |
| `GET /v2/state`                                                                  | `c3 state ls`     |
| `GET /v2/state/<store>`                                                          | `c3 state show`   |
| `DELETE /v2/state/<store>`                                                       | `c3 state rm`     |
| `GET /v2/state/<store>/keys?prefix=&cursor=&limit=`                              | `c3 state keys`   |
| `GET /v2/state/<store>/keys/<key>`                                               | `c3 state get`    |
| `PUT /v2/state/<store>/keys/<key>` with `{"value", "if_version"?, "if_absent"?}` | `c3 state put`    |
| `DELETE /v2/state/<store>/keys/<key>?if_version=`                                | `c3 state del`    |

URL-encode the key, including any `/`.

## Limits[​](#limits "Direct link to Limits")

| Limit                        | Beta value              |
| ---------------------------- | ----------------------- |
| Live stores per organisation | 20                      |
| Key size                     | 512 bytes               |
| Value size (as JSON)         | 64 KB                   |
| Keys per store               | 10,000                  |
| Data per store               | 100 MB                  |
| Requests                     | 600 per minute per user |

Going over a size or count limit returns `STATE_LIMIT_EXCEEDED` naming the limit. Going over the request rate returns `RATE_LIMITED`; the CLI waits and retries up to three times. State stores are free during the beta.

## Errors[​](#errors "Direct link to Errors")

| Code                    | Meaning                                                      | What to do                                        |
| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------- |
| `STATE_ACCESS_REQUIRED` | Your account is not in the beta                              | [Ask for access](https://cthree.cloud/beta)       |
| `STATE_STORE_NOT_FOUND` | No live store with that name in your organisation            | `c3 state ls`, or `c3 state create`               |
| `STATE_STORE_EXISTS`    | The name is already taken                                    | Pick another name, or use the existing store      |
| `STATE_KEY_NOT_FOUND`   | The key does not exist                                       | `c3 state keys <store>`                           |
| `STATE_CONFLICT`        | A conditional write or delete did not match; nothing changed | Read the key again and retry with the new version |
| `STATE_LIMIT_EXCEEDED`  | A limit above was exceeded                                   | Store less, or keep large data in a dataset       |
| `RATE_LIMITED`          | Over 600 requests a minute                                   | Slow down; retry after `Retry-After`              |
