Local Agent
Local Agent Quickstart
Create a local Agent with a persistent Workspace Sandbox and run its first Session
Local Agent Quickstart
Install
pnpm add @downcity/agent @downcity/city @downcity/federation @downcity/sandbox-microsandbox
npx microsandbox setup@downcity/sandbox-microsandbox is the cross-platform Sandbox Provider. It uses a separate persistent microVM environment for each Workspace.
Complete example
import { Agent } from "@downcity/agent";
import { City, Shell, Workspace } from "@downcity/city";
import { create_openai_compatible_model } from "@downcity/federation";
import { MicrosandboxProvider } from "@downcity/sandbox-microsandbox";
const model = create_openai_compatible_model({
id: "gpt-5",
upstream_model: "gpt-5",
base_url: "https://api.openai.com/v1",
api_key: process.env.OPENAI_API_KEY!,
});
const workspace = new Workspace({
id: "project",
path: "/path/to/project",
shell: new Shell({
sandbox_provider: new MicrosandboxProvider(),
}),
});
const agent = new Agent({ id: "repo-helper", model });
const city = new City({
workspaces: [workspace],
agents: [agent],
});
try {
const session = await agent.sessions.create({ workspace });
const turn = await session.prompt({
query: "Summarize the current repository structure",
});
console.log((await turn.finished).text);
} finally {
await city.close();
}Ownership
- City owns Plugins and registered resources, but does not know the Workspace execution backend.
- Workspace owns its project resources, environment, and optional Shell.
- Shell owns its Sandbox Provider, persistent Workspace Sandbox, and Shell Sessions;
shell_idand Chatsession_idare independent. - Agent owns Chat Sessions. A Chat Session borrows the selected Workspace but does not own its Shell or Sandbox.
Shell commands default to target: "sandbox" with the project mounted at /workspace. The same Workspace preserves HOME and installed tools across Chat Sessions. target: "host" requires a reason and approval. Sandbox startup failure never falls back to host execution.
Without Shell, Workspace still provides file and search tools. city.close() releases Agents, Plugins, and Workspaces; Workspace disposal delegates to Shell, which stops Sandbox compute while retaining its persistent filesystem.