downcity.json

downcity.json is the project configuration file. The CLI reads it at startup and passes its contents to the Agent SDK constructor. You can also use it as a reference when configuring the SDK directly.

Minimal structure

{
  "$schema": "./.downcity/schema/downcity.schema.json",
  "id": "my-agent",
  "version": "1.0.0",
  "start": {
    "port": 5314,
    "host": "0.0.0.0"
  },
  "execution": {
    "type": "api",
    "modelId": "default"
  },
  "plugins": {}
}

Key fields

• id — stable agent identifier. Used for session storage and runtime directories.
• start — runtime startup config (port, host). CLI flags override this if provided.
• execution — binds the project to a model ID from the connected Federation AIService.
• plugins — plugin-level configuration.

What should not live here

• Full model provider definitions (those live in City / Federation AIService).
• Plaintext API keys or bot credentials (those live in ~/.downcity/downcity.db or are injected through env).
• Console-level control plane settings.

Relationship to SDK

When you use the SDK directly, you pass the same values as constructor options. downcity.json is just a serialized form of those options for CLI convenience.

Continue with:

• Project Structure
• Profile