Downcity

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.

Why Downcity

• 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.
• Federation: centralize model catalogs, runtime env, service routing, accounts, balance, usage, and payment.
• 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.

Packages

Package	Purpose
downcity	Public CLI bundle: city/downcity is the local City container for Agent management, runtime, and console workflows; fed/downfed is the Federation Server Manager.
@downcity/workspace	Workspace resources, rooted files/search tools, environment, private storage, and built-in Shell.
@downcity/agent	Agent runtime and City container: AgentWorkspace, Session, Plugin SDK, multi-Agent ownership, and HTTP/RPC transport.
@downcity/federation	Federation runtime and Embassy SDK for Services, auth, env, Bureau, user, and admin access.
@downcity/type	Shared protocol types used across packages, including City model descriptors returned by City.
@downcity/services	Public services for accounts, balance, usage, payment, and Stripe payment flows.
@downcity/ui	React + Tailwind UI SDK for reusable Console and host-application components.
templates/*	Developer-friendly Agent, City, edge-runtime, and React UI starter applications.
homepage	Official website and end-user documentation site.

Core Capabilities

• Global Agent management: store Agent identity and config in the user-level Downcity data directory, while entering any Workspace at execution time.
• Local City hosting: run downcity on, downcity status, and downcity off to host all configured Agents in one CLI City.
• Agent operations: create, inspect, configure, and chat with globally managed Agents; Agents do not have an independent started/stopped state.
• Federation connection: use downcity federation to connect local Agents to the active Federation.
• Federation 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, sound, and workboard.
• Product surfaces: Downcity CLI, Agent SDK, City SDK, and UI SDK.

Platform Support

Platform	Local Agent and Safe Sandbox
macOS	Supported with Seatbelt
Linux	Supported with Bubblewrap
Windows 11 24H2+	Development / unstable with Microsoft MXC and native cmd.exe execution

Native Windows uses cmd.exe /d /s /c inside the Microsoft MXC processcontainer backend. Preflight requires Windows build 26100 or newer and a successful MXC isolation-tier probe; failures never fall back to unrestricted execution. MXC is currently Public Preview and is not presented as a production security boundary. See the Agent SDK Shell documentation for current limitations.

Quick Start

1. Install the CLI

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

The package exposes the downcity command (alias city):

downcity --version

downcity is the local City container for managing and running Agents through City() and the Agent SDK. Upgrade with npm i -g downcity@latest. The same package also provides fed/downfed for Federation Server management.

2. Connect to Federation

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.

3. Create an Agent

Run this inside the target repository:

downcity agent create .

This registers the Workspace path and creates an Agent definition under the user-level Downcity directory:

~/.downcity/
├── agents/
│   └── <agent_id>/
│       ├── agent.json
│       └── SOUL.md
└── plugins/
    └── <plugin_id>/

4. Start the CLI City

downcity agent list
downcity on
downcity status
downcity agent token create <agent_id> --name local

Invoke Plugin capabilities through city plugin action <plugin> <action> [agent_id].

To run the City in the foreground:

downcity on --foreground

5. Inspect Agents

downcity agent list

Chat remains available while the CLI City is off; the CLI creates and disposes a temporary local City:

downcity agent list
downcity agent chat <agent_id>

SDK Example

Local agent

import { Agent } from "@downcity/agent";
import { Shell, Workspace } from "@downcity/workspace";
import { MacOsSeatbeltSandbox } from "@downcity/sandbox-macos";
import { createOpenAI } from "@ai-sdk/openai";

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

const workspace = new Workspace({
  id: "project",
  path: "/path/to/project",
  shell: new Shell({ sandbox: new MacOsSeatbeltSandbox() }),
});
const agent = new Agent({ id: "repo-helper", tools: {} });

const session = await agent.sessions.create({ workspace });
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.

Remote agent

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);

Repository Layout

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

The templates/* projects are convenient developer starters and showcases. The ui template is a standalone React + Vite application for previewing the public @downcity/ui components.

Documentation

• 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/type/README.md, packages/services/README.md, packages/cli/README.md, packages/ui/README.md

Local Development

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:ui-template
pnpm dev:homepage

Security and Runtime Notes

• 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.