ship.json Reference

Model config is now split into two layers:

1. ~/.ship/ship.db (console-global SQLite) manages the full model pool
2. Project ship.json (agent-local) only sets model.primary

Agent project minimal shape

{
  "$schema": "./.ship/schema/ship.schema.json",
  "name": "my-agent",
  "version": "1.0.0",
  "model": {
    "primary": "default"
  }
}

model.primary must match an existing model id in ~/.ship/ship.db.

Project ship.json should not configure extensions.*.

Console-global model pool

Full model management stays in ~/.ship/ship.db:

• providers table
• models table
• provider apiKey is encrypted at rest (api_key_encrypted)

Use CLI:

city console model list
city console model get provider openai_main

Runtime resolution

At agent runtime:

1. Read project model.primary
2. Resolve model in SQLite models table by id
3. Resolve provider in SQLite providers table by providerId

If any link is missing, startup fails fast.

Extension scope

extensions.* is console-global and loaded from ~/.ship/ship.db (extensions_config). Project-level ship.json is not the place to configure extensions.

Chat channel binding

Chat channels in ship.json should bind to a global channel account id:

{
  "services": {
    "chat": {
      "channels": {
        "telegram": {
          "enabled": true,
          "channelAccountId": "telegram-main"
        }
      }
    }
  }
}

channelAccountId resolves to channel_accounts.id in ~/.ship/ship.db.

Related docs

• Model Config Reference
• city console config