Configuration

Downcity is configured with four core files:

• PROFILE.md: agent role and boundaries (required)
• SOUL.md: stable operating principles (optional)
• USER.md: user preferences (optional)
• ship.json: runtime configuration (required)

Key ship.json fields

start (advanced only)

For city agent start, ports are auto-allocated by console.

So in normal usage you do not need start.port in project ship.json.

Only configure start when manually running foreground runtime or debugging special host binding:

{
  "start": {
    "host": "0.0.0.0"
  }
}

model

Agent model binding (maps to console-global model pool):

{
  "model": {
    "primary": "default"
  }
}

services.chat

Chat channels and queue behavior:

{
  "services": {
    "chat": {
      "method": "direct",
      "queue": {
        "maxConcurrency": 2,
        "mergeDebounceMs": 600,
        "mergeMaxWaitMs": 2000
      },
      "channels": {
        "telegram": {
          "enabled": true,
          "channelAccountId": "telegram-main"
        }
      }
    }
  }
}

channelAccountId binds to the global channel account registry in ~/.ship/ship.db (channel_accounts).

services.chat.queue notes:

• maxConcurrency: max lane concurrency across different chat keys.
• mergeDebounceMs: short debounce window for batching consecutive inbound messages in one run.
• mergeMaxWaitMs: hard cap for the batching wait to avoid unbounded delay.

services.skills

Skills discovery roots:

{
  "services": {
    "skills": {
      "paths": [".agents/skills"],
      "allowExternalPaths": false
    }
  }
}

extensions.* (note)

Extension config is not maintained in project ship.json. It is maintained in console-global ~/.ship/ship.db.

Example for voice:

city voice on SenseVoiceSmall
city console config get extensions.voice

permissions

Repository write and command execution policies:

{
  "permissions": {
    "read_repo": true,
    "write_repo": { "requiresApproval": false },
    "exec_command": {
      "deny": ["rm"],
      "requiresApproval": false,
      "maxOutputChars": 12000,
      "maxOutputLines": 200
    }
  }
}

Useful commands

city console config get
city console config get model.primary
city console model list
city console config unset services.chat.channels.telegram

Next

• CLI Reference
• .ship/ Directory
• Environment Variable Strategy (Console Shared vs Agent Private)