English | 简体中文

Agent infrastructure for AI builders shipping many agent-powered products and workflows.

Downcity gives creators, indie builders, and teams one reusable runtime layer for agents, models, tools, tasks, memory, plugins, City, permissions, usage, billing, and control surfaces. Instead of rebuilding the same agent backend for every new AI product, you can run many agents, products, and workflows on one infrastructure stack.

• Built for AI builders: create the next agent product without rebuilding model routing, tools, memory, tasks, auth, usage, billing, and operations again.
• Reusable runtime layer: a repo or folder can become an agent boundary, while Downcity owns the broader infrastructure for long-running agents.
• City: centralize model catalogs, runtime env, service routing, accounts, balance, usage, payment, and HTTP access.
• Operable agents: run agents as managed daemons, inspect status, review history, and interact through CLI or SDK.
• Extensible architecture: plugins, services, SDK APIs, and UI components are explicit integration surfaces for products and teams.

• Agent project runtime: initialize a repo or folder with PROFILE.md, SOUL.md, downcity.json, and .downcity/.
• Local agent operations: run downcity agent start, downcity agent status, and downcity agent list to host and inspect local agents.
• Agent lifecycle: create, start, stop, restart, inspect, chat with, diagnose, and observe project agents.
• City connection: use downcity federation to connect local Agents to the active City server; manage City models and Service resources with city.
• City backend capabilities: reuse accounts, balance, usage, payment, env, auth, and Service routing across agents and products.
• Built-in agent capabilities: chat, task, memory, shell, contact, skill, web, asr, tts, and workboard.
• Product surfaces: Downcity CLI, Agent SDK, City SDK, and UI SDK.

npm install -g downcity
# or
pnpm add -g downcity

The package exposes the downcity command (alias city):

downcity --version

downcity hosts and manages local Agents and administers the City. Use downcity update to upgrade the global CLI.

downcity init

This sets up the global Downcity storage and configuration, by default under ~/.downcity/.

downcity federation use
downcity federation status

downcity manages City models and Service resources. downcity federation imports the active City connection for local Agent runtime use.

Run this inside the target repository:

downcity agent create .

This creates or updates:

your-project/
├── PROFILE.md
├── SOUL.md
├── downcity.json
├── .agents/
│   └── skills/
└── .downcity/
    ├── cache/
    ├── config/
    ├── data/
    ├── debug/
    ├── logs/
    ├── profile/
    ├── public/
    ├── schema/
    ├── session/
    └── tasks/

downcity agent start .
downcity agent status .
downcity agent chat -m "Summarize this repository"
downcity agent chat --new-session

Interactive chat can also pick an existing session or create a new one before the TUI opens.

To run in the foreground:

downcity agent start . --foreground

downcity agent list

Useful status commands:

downcity agent list
downcity agent status .

import { Agent } from "@downcity/agent";
import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
});

const agent = new Agent({
  id: "repo-helper",
  path: "/path/to/project",
  tools: {},
});

const session = await agent.session();
await session.set({
  model: openai.responses("gpt-5"),
});

const turn = await session.prompt({
  query: "Summarize the repository structure",
});
const result = await turn.finished;

console.log(result.text);

@downcity/agent does not resolve provider or model IDs for you. In SDK mode, the host application creates the model and injects it into the session.

import { RemoteAgent } from "@downcity/agent";

const agent = new RemoteAgent({
  baseUrl: "http://127.0.0.1:15314",
});

const session = await agent.session();
const turn = await session.prompt({
  query: "Check the latest task execution status",
});
const result = await turn.finished;

console.log(result.text);

downcity/
├── packages/
│   ├── agent/
│   ├── city/
│   ├── cli/
│   ├── services/
│   ├── type/
│   └── ui/
├── templates/
│   ├── edge/
│   └── node/
├── homepage/
├── scripts/
├── package.json
└── pnpm-workspace.yaml

The templates/* projects are kept as convenient developer starters. They are not the private official production deployments.

• Docs: downcity.ai/docs
• City SDK docs: downcity.ai/city-sdk-docs
• Agent SDK docs: downcity.ai/agent-sdk-docs
• UI SDK docs: downcity.ai/ui-sdk-docs
• Chinese overview: README.zh-CN.md
• Package docs: packages/agent/README.md, packages/city/README.md, packages/type/README.md, packages/services/README.md, packages/cli/README.md, packages/ui/README.md

Install dependencies:

pnpm install

Build:

pnpm build
pnpm build:agent
pnpm build:city
pnpm build:homepage

Typecheck:

pnpm typecheck
pnpm -C packages/ui typecheck
pnpm -C homepage typecheck

Run in development mode:

pnpm dev:city
pnpm dev:agent
pnpm dev:ui-sdk
pnpm dev:homepage

• Downcity can execute shell commands, read and write project files, start local daemons, and receive external messages through chat channels.
• Local shell and script commands run through the agent sandbox by default. The project is writable, network is open, and sandbox HOME/cache lives at .downcity/sandbox.
• Use a clean Git branch and audit changes with git status and git diff.
• Keep secrets out of the repository; prefer local environment variables or downcity env.
• Use tokens and auth boundaries for Console, HTTP access, and chat channel integrations.
• Host-level installs such as sudo, brew install, Xcode tools, and writes to system directories are outside the sandbox boundary.