Getting Started

1. Install

npm install -g downcity
# or
pnpm add -g downcity
studio --version
city --version

downcity exposes studio for local agents and city for City administration.

If studio is not found after install, see FAQ.

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

2. Initialize Studio (first time only)

studio init

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

3. Start Studio

studio start

studio agent start requires console to be running first.

4. Initialize a repository

cd /path/to/your-repo
studio 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 Studio 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):

studio 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:

studio agent start --foreground

7. Verify agent state

studio agent list
studio agent status
studio 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

studio start --console

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
• studio skill
• studio task
• FAQ