Getting Started

1. Install

npm install -g @downcity/city
# or
npm install -g downcity
# or
pnpm add -g @downcity/city
# or
pnpm add -g downcity
city --version
downcity --version

downcity and city are the same CLI binary.

@downcity/city and downcity publish the same CLI contents and version line.

If city is not found after install, see FAQ.

To upgrade later, run city update. It upgrades the package you originally installed.

2. Initialize Console (first time only)

city init

This creates console-global config under ~/.downcity/.

3. Start Console

city start

city agent start requires console to be running first.

4. Initialize a repository

cd /path/to/your-repo
city agent create .

Initialization generates:

• PROFILE.md (required)
• SOUL.md (optional)
• downcity.json
• .downcity/ runtime directory

5. Bind a model

The current project agent uses the global model-pool binding style.

The minimal downcity.json example should be:

{
  "name": "my-agent",
  "version": "1.0.0",
  "execution": {
    "type": "api",
    "modelId": "quality"
  }
}

Notes:

• modelId points to a model in the city global model pool
• the project no longer stores the old model.primary structure
• if you have not prepared a model pool yet, do that first at the global level

6. Start Agent

Start the agent (default: background daemon):

city agent start

If you run this outside an initialized agent directory, Downcity can let you pick from registered agents interactively.

Use foreground mode when you want logs in the current terminal:

city agent start --foreground

7. Verify agent state

city agent list
city agent status
city agent list --running

Notes:

• Agent ports are auto-allocated by console, so Quickstart should not assume a fixed port.
• In multi-agent setups, each agent can have a different port.

8. Optional: start Console UI

city start

9. Optional: Chrome extension quick-send from page selection

If you use the repo's chrome-extension:

1. Select text on the page, then click the message button near the selection to open the inline input near the selected area.
2. Clicking the browser extension action icon opens the Extension Popup; press Cmd/Ctrl + U to open the Inline Composer on the page.
3. The Extension Popup stays minimal: one input box, one send button, page-level send history, and a settings button.
4. Agent switching in the Extension Popup is intentionally minimal; Channel Chat is auto-resolved from the current Agent's first available conversation.
5. Click a history item to refill a previous ask from the current page.
6. Press Cmd/Ctrl + Enter or click the send button to submit (Enter for newline).
7. Press Esc to close the input box.
8. If nothing is selected, sending automatically falls back to full-page mode.
9. Full-page mode prefers the strongest main/article content region; if the page has multiple strong content roots, it merges them and includes page image references.

Next

• Configuration
• Agent Overview
• city skill
• Task Service
• FAQ