---
title: 'config'
description: 'Read, write, version and roll back the AGENT_CONFIG document of a running agent installation, and regenerate its local TypeScript types'
position: 22
---

# stackbone config

> `stackbone config` 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).
> `rollback` is a
> [destructive verb](/docs/cli/reference/conventions#destructive-verbs) that
> refuses to run without `--yes`. Every verb emits the shared
> [JSON envelope](/docs/cli/reference/conventions#json-output) under `--json`.
> The one exception to all of this is `config types`, described below: it is
> local codegen and reaches no installation.

Manage the agent's `AGENT_CONFIG` document on the targeted installation.
The control plane models config as **one versioned JSON document**:
every write appends a new version, and the highest one is active.
A rollback copies a prior version forward.

The agent reads this document at runtime through
[`stackbone.config`](/docs/sdk/platform/config). The CLI's own settings (the
global flags, config files and exit codes of the `stackbone` binary itself) live
on [Configuration](/docs/cli/reference/configuration).

| Command                                   | Purpose                                                                   |
| ----------------------------------------- | ------------------------------------------------------------------------- |
| `stackbone config get`                    | Print the active config document (value, version, author).                |
| `stackbone config set`                    | Persist a new version. Reads a JSON object from `--file <path>` or stdin. |
| `stackbone config versions`               | List recent versions (newest first, up to 100).                           |
| `stackbone config rollback --version <n>` | Roll the active config back to a prior version. Requires `--yes`.         |
| `stackbone config types`                  | Regenerate `.stackbone/config.d.ts` from your `config.schema.ts`.         |

**JSON payload**

```jsonc
// config get: `schema` is the JSON Schema built from your config.schema.ts, or null
{ "schema_version": 1, "version": 4, "value": { "feature": { "newFlow": true } },
  "schema": { "type": "object", "properties": { "feature": {} } },
  "updatedAt": "2026-06-01T10:00:00Z", "updatedBy": "a@b.com" }

// config set: previousValue lets a caller diff the two
{ "schema_version": 1, "unchanged": false, "previousValue": { "feature": { "newFlow": false } },
  "config": { "version": 5 } }

// config versions
{ "schema_version": 1,
  "items": [{ "version": 5, "value": {}, "rolledBackFrom": null,
              "createdAt": "2026-06-01T10:00:00Z", "createdByEmail": "a@b.com" }] }
```

The config value must be a JSON **object** (never a primitive or array).
Anything else fails before the network call.

`set` enforces a declared schema. When your project has a
`config.schema.ts`, the installation validates the incoming document against it
and refuses one that does not match. With no `config.schema.ts` the document is
free-form. The installation reads the schema that
[`stackbone build`](/docs/cli/reference/build) compiled into the bundle, so a box
validates the same document `stackbone dev` accepted. `rollback` skips the check:
it replays a version the installation already stored.

`set` and `rollback` write a new version only when the value differs from the
active one. An identical document comes back with `"unchanged": true` and the
version stays where it is.

`stackbone config types` runs on your machine, unlike the other four verbs on
this page. It reads `config.schema.ts` and rewrites `.stackbone/config.d.ts` so
`stackbone.config.get('<key>')` autocompletes in your editor. It takes no
`--agent` and reaches no control plane, so you need no running
[`stackbone dev`](/docs/cli/reference/dev).
`--cwd <dir>` points it at a project other than the current directory.
`stackbone dev` runs the same codegen on boot and on every edit of that file, so
you only need the verb when the stack is down.

**Exit codes**: `0` ok · `4` not found (unknown version) · `5` permission
(`rollback` without `--yes`) · `1` generic (input not a JSON object).

## Model provider

There is no CLI group for the LLM credential. The **operator** who runs
the deployment configures the model provider from the Studio
**Model provider** screen, and the value lives inside that deployment:
the control plane never holds it. See
[Local development → model provider](/docs/cli/guides/local-development#model-provider)
for how `stackbone dev` resolves it on your machine.