English | 简体中文
Atelier is a personal AI workbench built on the Pi Code Agent SDK. It turns "chatting with an agent" into "delivering finished work": you start a task with a single sentence, the system drives the agent inside an isolated sandbox to do research, writing, and data work, and the results land as versioned files and conclusions. Preferences and facts learned along the way are consolidated into a cross-task Memory Wiki.
| Task chat — traceable agent execution | Capability market — expert suites / skills / MCP |
|---|---|
 |
 |
| Memory Wiki — agent-maintained long-term memory | File space — 50+ in-browser preview formats |
|---|---|
 |
 |
| Automations — scheduled & workflow tasks | Governance — approvals, quotas, audit |
|---|---|
 |
 |
- Sessions are tasks. One session = one task = multiple runs. The agent writes final deliverables into the sandbox
deliverables/directory; they sync automatically as versioned artifacts. Every turn is grouped with its reasoning, tool calls, and final answer — expandable, interruptible, retryable. - Automatic delegation (agent team). Beyond single-agent execution, a supervisor agent picks matching expert suites, runs subagents concurrently in the same sandbox, and merges their results.
- Expert suites, skills, and MCP. Role packages (system prompt × skills × MCP connections), 40+ Chinese office-scenario remote skills pinned to immutable commits with SHA-256 verification, per-turn plugins, and MCP 2.0 Streamable HTTP connections with encrypted per-user tokens.
- Memory Wiki. Long-term memory is a Markdown wiki the agent maintains itself — an
index.mdplus topic pages. Enable it per turn: the agent reads the index before working and writes stable conclusions back. Human-editable, pinnable, full-text searchable (TF-IDF + CJK bigrams). - File space. Personal drive with automatic archiving of task outputs and online preview for 50+ formats (Office, PDF, Markdown, images, CSV, code).
- Automations. Interval / daily / weekly / one-shot tasks with multi-step workflow orchestration; runs are created paused and activated after confirmation.
- Security governance. Two-phase approvals for high-risk actions: a signed capability is issued on human approval and verified at execution time, with quotas, budgets, and a full audit trail.
- IM channels. Feishu (official SDK WebSocket long connection) and WeChat (bridge QR login); IM sessions share the same resume semantics as the web, including approvals from chat.
- Voice input. Browser-native dictation first, PCM recording + transcription as fallback, then an AI pass that polishes spoken transcription into clean written text.
- Observability. Structured JSON logs with secret redaction, OTel spans, and a Langfuse trace sink recording every turn's input/output.
Web (React 19 + Vite 6 + Tailwind 4)
│ REST + SSE (AG-UI style event stream, resume by seq)
▼
Fastify API (control plane)
└─ AtelierService (business orchestration, the only stateful class)
├─ DatabaseAdapter SQLite (local) / PostgreSQL (prod), transactional outbox
├─ BlobStore file:// (local) / S3·MinIO (prod)
├─ SandboxProvider LocalProcess / Docker / E2B
├─ AgentEngine PiSdk (prod) / Deterministic (tests) / OpenAI-compatible
├─ LifecycleScheduler RocketMQ delayed messages (hibernate/destroy scheduling)
└─ AgentTraceSink Langfuse / Noop
│ uploads request JSON + Pi session JSONL; passes secrets via stdin;
│ streams events back over stdout
▼
Docker sandbox (execution plane, Node 26 + Python 3)
└─ agentd → Pi SDK: runs the session with a tool allow-list
├─ Remote skills: zero-mount, fetched on demand + SHA-256 verified
├─ MCP tools: Streamable HTTP, mcp_<server>_<tool>
├─ Wiki tools: wiki_list / wiki_search / wiki_read / wiki_write
└─ workflow tool: script orchestration agent() / parallel() / pipeline()
One task, end to end: POST /v1/sessions/{id}/messages → transactional write of message/task/run + frozen snapshot (experts/skills/plugins/memory) → outbox → worker acquires the session lease → creates or reuses a sandbox → exports the Memory Wiki, uploads attachments, restores the Pi session → agentd executes → events stream back in real time → end-of-turn write-back (versioned Pi JSONL into blob storage, wiki page diff into DB, deliverables synced as artifacts) → sandbox returns to warm idle.
Sandbox lifecycle: running → warm_idle (default 600s) → hibernated (docker stop, until 1800s) → destroyed. Every turn's Pi JSONL is versioned into the blob store; a destroyed sandbox is transparently recreated and state restored from the latest version — web conversations, IM sessions, and retries all share the same resume semantics.
Requirements: Node.js 26, pnpm 11, local Docker.
corepack enable
pnpm install
pnpm dev:local # API (8787) + Web (5173), Docker sandboxesWithout MODEL_API_KEY a deterministic test agent is used; once configured (any OpenAI Chat Completions-compatible endpoint) the real Pi SDK runs inside Docker sandboxes. Environment files load .env first, then .env.local (local overrides, not committed).
| Command | What it does |
|---|---|
pnpm dev |
Watch all packages in parallel (turbo) |
pnpm dev:local |
Local dev stack (API + Web) |
pnpm build / pnpm typecheck / pnpm test |
Build / type check (doubles as lint) / all vitest suites |
pnpm test:e2e:local |
Full local E2E (Docker sandbox + deterministic agent) |
pnpm test:e2e:infra |
Production-compatible E2E (PostgreSQL + MinIO + Docker) |
pnpm test:smoke:pi-docker |
Real-model sandbox smoke test (skipped without a key) |
docker compose --profile build-runtime build runtime-image |
Rebuild the sandbox image (required after runtime changes) |
To switch to PostgreSQL / MinIO: docker compose up -d postgres minio minio-init, then set DB_DRIVER=postgres, BLOB_DRIVER=s3 and connection details in .env.local (see .env.example).
apps/
api/ Fastify control plane: routes, AtelierService, approvals, SSE
agentd/ In-sandbox process: reads request JSON → runs Pi SDK → streams events
worker/ Optional dedicated worker: outbox drain, lifecycle, automation tick
web/ React 19 + Vite 6 + Tailwind 4 frontend
packages/
contracts/ Zod contracts (single source of truth for DTOs)
db/ DatabaseAdapter: SQLite (WAL/FTS5) / PostgreSQL
sandbox/ SandboxProvider: LocalProcess / Docker / E2B
workspace/ BlobStore: File / S3·MinIO + object key generators
agent-runtime/ AgentEngine: PiSdk / Deterministic / OpenAI-compatible + wiki/workflow tools
capabilities/ Skill catalog, plugin catalog, builtin skills, remote fetch & verification
policy/ Action risk evaluation, capability signing, canonical JSON
scheduler/ Lifecycle delayed messages (RocketMQ)
observability/ OTel, Langfuse sink, redacting logger
im/ Feishu SDK long connection / WeChat bridge / stub
infra/runtime/ Sandbox image (Node 26 + Python 3 + pnpm)
scripts/ dev-local / e2e-local / e2e-infra / smoke tests
docs/ Technical design and topic deep-dives (see below)
| Document | Contents |
|---|---|
| docs/technical-design.md | Full technical design: architecture, execution flow, Pi runtime, sandboxes, experts/skills, swarm, isolation, data model, API, state machines |
| docs/sandbox-architecture.md | Sandbox three-state lifecycle |
| docs/capability-center-expert-design.md | Capability center & expert design |
| docs/capability-research.md | Research on the Pi plugin ecosystem (why a curated catalog) |
| docs/deploy-local.md | Local deployment guide (PostgreSQL/MinIO/RocketMQ shapes) |
| docs/deploy-production.md | Production deployment on Kubernetes (ACK) |
| AGENTS.md | Repository conventions for AI collaborators |
- One private workspace per user; one sandbox per session; subagents in the same sandbox share the data boundary but keep independent sessions.
- Every DB query is owner-scoped; object keys are anchored to
users/{base64url(userId)}/workspace/; attachments, memory, and artifacts are ownership-checked before enqueueing. - Sandboxes run with
--memory 1g --cpus 1; secrets reach the sandbox only via stdin; logs and event streams apply two layers of redaction. - Default seed account is
admin / admin123— change it immediately in any real deployment.