---
title: 'contract'
description: 'Inspect the Stackbone Agent Protocol contract a running agent installation advertises, and validate the local agent.yaml against it'
position: 24
---

# stackbone contract

> Every verb here targets a **running agent installation** and resolves it the
> standard way: the local-dev installation linked to the current project unless
> you pass `--agent <installationId>`. See
> [target resolution](/docs/cli/reference/conventions#target-resolution).
> All three verbs are read-only, so none of them needs `--yes`. They accept
> `--json` and emit the usual
> [`{ "schema_version": 1, ... }` envelope](/docs/cli/reference/conventions#json-output).

Inspect the Stackbone Agent Protocol contract the targeted installation
advertises, and validate the local project against it.

| Command                           | Purpose                                                                                                                                                  |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stackbone contract show`         | Print the full contract (version, build, runtime URL, capabilities).                                                                                     |
| `stackbone contract capabilities` | List the capabilities the installation reports (e.g. `queues.jobs`, `storage.s3`).                                                                       |
| `stackbone contract validate`     | Validate the local `agent.yaml` against the target's contract (or the local emulator contract when no installation is linked). Run it before you deploy. |

`capabilities` comes from the same handshake `show` reads: there is no
separate endpoint. `validate` fails (exit `1`) when the contract version is
unsupported or the target does not advertise a declared capability. Run it
before you build an image and register it with
[`stackbone link`](/docs/cli/reference/link). There is no publish
command: you host the workspace bundle yourself. See
[Going to production](/docs/cli/reference/commands#going-to-production).

These three verbs report the **installation-level** contract: the protocol
version and the capability strings the running box advertises. It carries no
input/output schemas. A workspace agent declares its input/output contract
**per workflow**, so the durable-workflow surface is the canonical view for
schemas: use [`stackbone workflows schema <name>`](/docs/cli/reference/workflows#stackbone-workflows-schema)
to read one workflow's input/output JSON Schema, and
[`stackbone workflows list`](/docs/cli/reference/workflows#stackbone-workflows-list)
to see which workflows declare one.

**Flags** (all three verbs take the same one)

| Flag           | Type     | Description                                                                               |
| -------------- | -------- | ----------------------------------------------------------------------------------------- |
| `--agent <id>` | `string` | Installation id to target. Defaults to the local-dev installation linked to this project. |

## stackbone contract show

Prints the handshake the targeted installation serves: the protocol version it
speaks, the lowest version it still supports, the build that answered, the
public runtime URL for this install (`-` when it reports none), and the
capability list.

```bash
stackbone contract show
stackbone contract show --agent inst_123 --json
```

**JSON payload**

```jsonc
// contract show
{
  "schema_version": 1,
  "contract": {
    "version": 15,
    "minSupported": 1,
    // "stackbone-cli" (the local emulator) or "stackbone-api" (a deployed box)
    "build": { "name": "stackbone-cli", "version": "0.3.3" },
    "runtimeUrl": "https://example.invalid",
    "capabilities": ["database.postgres_direct", "storage.s3", "prompts.basic"],
  },
}
```

Only the per-install handshake populates `runtimeUrl`. It is `null` when the
install has no reachable runtime (an offline local dev session). The local
emulator contract omits the field.

## stackbone contract capabilities

Lists the capability strings the installation reports, one per line, or
`No capabilities advertised.` when the list is empty. It reads the same
handshake as `show` (there is no separate endpoint). Use it when a script
needs one fact without parsing the whole contract.

```bash
stackbone contract capabilities
stackbone contract capabilities --json
```

Capability membership is additive: a box may advertise a string this CLI has
never heard of, and that is not an error.

**JSON payload**

```jsonc
// contract capabilities
{
  "schema_version": 1,
  "capabilities": [
    "database.postgres_direct",
    "rag.basic",
    "queues.jobs",
    "secrets.read_write",
    "config.read_write",
    "approval.fire_and_forget",
    "storage.s3",
    "ai.openrouter",
    "prompts.basic",
    "browser.provider",
  ],
}
```

That list is what the local emulator advertises. A deployed box advertises the
subset its own build serves, so read the list rather than assuming it.

## stackbone contract validate

Reads the [`agent.yaml`](/docs/cli/reference/agent-yaml) in the current
directory and checks it against the contract the target advertises. Two checks
run: the contract version is still one this CLI can execute, and the contract
advertises every capability the manifest declares.

```bash
stackbone contract validate
stackbone contract validate --agent inst_123 --json
```

`validate` reads the manifest first. `agent.yaml` is optional in a workspace
and `stackbone init` does not write one, so run this verb only from a directory
that has one. Without it the command exits `3` before it touches the network.

With a manifest in place, `validate` still works when nothing is linked yet: if
there is no installation to resolve, it falls back to the local emulator
contract instead of failing. The JSON `source` field says which contract it
compared against, `install` or `local-emulator`. A linked project with no
`stackbone dev` running is a different case. The CLI reports `dev_not_running`
(also exit `3`) instead of falling back.

The check is best-effort on the manifest side. The `agent.yaml` schema has no
`capabilities` field and rejects unknown keys, so no manifest declares one:
only the version check runs, and `deviations` records what the check skipped
instead of failing the command. The CLI records an entry outside the protocol
allowlist the same way, and never drops it.

**JSON payload**

```jsonc
// contract validate
{
  "schema_version": 1,
  "ok": true,
  "violations": [],
  // one line per manifest detail the check could not read, e.g.
  // "agent.yaml declares no `capabilities`"
  "deviations": [],
  "contractVersion": 15,
  "source": "install",
}
```

**Exit codes**: `0` ok · `3` no project (no `agent.yaml`, or the local-dev
target has no `stackbone dev` running) · `1` generic (validation failed,
contract incompatible). See
[exit codes](/docs/cli/reference/conventions#exit-codes).