# OpenBMB/PilotDeck: a WorkSpace-based agent runtime for long-running, multi-project work

> PilotDeck is an AGPL-3.0 TypeScript agent platform from THUNLP, ModelBest, OpenBMB and AI9Stars that isolates files, memory and skills per WorkSpace. The interesting part is white-box memory and cost-aware model routing; the unproven part is everything the README asserts with numbers.

**OpenBMB/PilotDeck** — Task-oriented AI Agent productivity platform

- Repository: https://github.com/OpenBMB/PilotDeck
- Website: https://pilotdeck.openbmb.cn
- Stars: 4,023 · Forks: 456
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/openbmb-pilotdeck

## The problem PilotDeck targets: parallel projects that poison each other's context

Most agent tooling assumes one conversation, one task, one sitting. PilotDeck assumes the opposite. Its README frames the project around "long-running, multi-project productivity work" and asks four questions that a single chat window cannot answer: whether memory stays white-box and traceable when many projects run at once, whether token cost can be tracked per task, whether task difficulty can be routed to different models automatically, and whether work continues after you leave the keyboard.

The unit of organisation is the WorkSpace. According to the README, every project gets its own file system, memory store and skill set, so parallel work does not interfere and retrieval has a bounded scope. That is a real design decision, not a slogan: it means the retrieval index a task sees is scoped to one project rather than a global pool. The intended audience is someone running several concurrent workstreams, not a developer who wants autocomplete in an editor.

## WorkSpace isolation, white-box memory and the three pillar capabilities

PilotDeck describes three capabilities on top of the WorkSpace container. The first is white-box memory: the README states that memory generation, extraction, storage and retrieval are visible end to end, so when the agent mis-remembers something you can locate the offending entry and edit it instead of starting a new chat. There is also a Dream Mode that consolidates memory during idle windows, with one-click rollback.

The second is Smart Routing. Task difficulty is detected automatically; the README says complex calls go to flagship models such as Claude 3.5 Sonnet or GPT-4o while simple ones drop to lighter models, with on-device and cloud co-orchestration.

The third is Always-on background execution, which the README describes as breaking the ask-and-answer loop: the agent keeps discovering candidate tasks, runs long-horizon monitors, and lands deliverables as local files with a summary report. The system is MCP-native and behaves consistently across Web, CLI and IM front-ends. Note that the README's cost figure, roughly 70% savings, is reported for one Xiaohongshu-style social-media operation; it is not a general benchmark, and the README does not publish the measurement method.

## Installing PilotDeck with Docker Compose and reaching the web UI

The repository ships a Dockerfile and a docker-compose.yml, and the compose file is the shortest path to a running instance. It builds the image locally, maps port 3001 on the host to 3001 in the container, and mounts a named volume at /root/.pilotdeck so generated config, the auth database, permissions, sessions, memory, skills and router stats survive restarts.

```yaml
services:
  pilotdeck:
    build: .
    image: pilotdeck:latest
    ports:
      - "3001:3001"
    volumes:
      - pilotdeck-home:/root/.pilotdeck
    restart: unless-stopped
```

Bring it up with the standard compose command, then open the host on port 3001 in a browser.

```bash
docker compose up -d
```

The container sets NODE_ENV=production, PILOT_HOME=/root/.pilotdeck, SERVER_PORT=3001 and PILOTDECK_GATEWAY_PORT=18789. Local authentication is disabled by default; the compose file shows that uncommenting PILOTDECK_DISABLE_LOCAL_AUTH=0 turns login on. If you are behind a corporate proxy, the file also lists https_proxy and PILOTDECK_PROXY as commented options.

Instead of mounting a config file, you can supply credentials through environment variables. The compose file names PILOTDECK_MODEL, PILOTDECK_API_KEY and PILOTDECK_API_URL as the alternatives.

```bash
PILOTDECK_MODEL=openai/gpt-4.1
PILOTDECK_API_KEY=sk-xxx
PILOTDECK_API_URL=https://api.openai.com/v1
```

For a source install, package.json requires Node >=22.13.0 and <23, and the repository carries install.sh, install.ps1, README_SOURCE_INSTALL.md and README_DOCKER.md alongside the main README. The build script compiles edgeclaw-memory-core first, then TypeScript, and copies builtin plugins into dist. The server entry point is exposed as the pilotdeck binary and as npm run server, which runs src/cli/pilotdeck.ts through tsx.

## Where PilotDeck is the wrong tool, and where the documentation goes quiet

The Dockerfile is explicit that the Electron workspace is kept out of the Docker context and "must never add desktop dependencies to this image." The Web image installs only the pilotdeck and pilotdeck-ui workspaces. Desktop packaging is a separate path through pnpm --filter pilotdeck-desktop, which means a container-first deployment is not the same product as the desktop build.

The README does not document what a Dream Mode rollback discards, nor how conflicts between a rolled-back memory entry and later entries are resolved. It also does not explain how the router classifies task difficulty, so there is no way to predict from the documentation which calls will be demoted. If your work is a single short task, or you need an assistant embedded in an editor rather than a WorkSpace with its own filesystem and memory store, the isolation model is overhead you will pay for and never use.

## How PilotDeck differs from Claude Code and Cursor

The README positions PilotDeck against three named alternatives. Claude Code, Cursor and Trae Solo bring model reasoning into the programming IDE. Claude Cowork introduced project-level isolation to desktop knowledge work. WorkBuddy connected agents to IM ecosystems such as WeCom and Feishu.

The difference is the axis each tool optimises. An IDE agent optimises the edit-test loop inside a repository you already have open. PilotDeck optimises the container around the work: per-project files, memory and skills, plus a router that decides which model handles a call. If your bottleneck is typing speed inside one codebase, an IDE agent is the better fit. If your bottleneck is that five projects share one context window and you cannot tell why the agent remembered the wrong detail, the WorkSpace model is the argument for PilotDeck.

## Licence and the cost of keeping a self-hosted agent current

PilotDeck is licensed AGPL-3.0. That matters if you modify the code and expose it to users over a network, because the licence's network clause is broader than permissive licences in how it treats that case. This is a description of the licence, not legal advice; read the LICENSE file and get your own counsel if you plan to offer a modified PilotDeck as a service.

The upgrade cadence is visible in the release list. Releases v2026.09.07, v2026.09.09 and v2026.09.10 landed within four days of each other, and the last push to main was on 2026-09-10. Frequent versioned releases mean a self-hosted deployment needs a repeatable upgrade path, and the compose file's named volume is what protects your state across a rebuild: config, auth database, permissions, sessions, memory, skills and router stats all live under /root/.pilotdeck. Rebuild the image without that volume and you lose the memory store the product is built around. Node is pinned to the 22.x line by the engines field, and the Dockerfile pins pnpm to 10.32.1 with a note that the pin exists so CI does not pick up stricter build-script policy changes before the lockfile is updated.

## Conclusion

Adopt PilotDeck if you run several long-lived projects in parallel and want memory entries you can inspect and edit rather than a chat history you cannot audit. Skip it if you need a single-shot coding assistant inside an IDE, or if AGPL-3.0 terms do not fit how you distribute software. Before committing, verify two things yourself: that the Smart Routing cost claim holds on your own traffic, since the README reports it for one social-media workflow only, and that Dream Mode's one-click rollback behaves as described, because the README does not document what a rollback discards.

## FAQ

### How do I install PilotDeck?

The repository provides a Dockerfile and docker-compose.yml; the compose file builds the image, maps port 3001 to the container and mounts a named volume at /root/.pilotdeck for state. Source installs are covered by install.sh, install.ps1 and README_SOURCE_INSTALL.md, and package.json requires Node >=22.13.0 and <23.

### What is OpenBMB/PilotDeck used for?

PilotDeck is described as a task-oriented AI agent productivity platform built around the WorkSpace, where each project gets its own file system, memory store and skill set. It adds white-box memory, automatic model routing by task difficulty, and background execution that lands deliverables as local files.

### Does PilotDeck require authentication by default?

No. The docker-compose.yml leaves PILOTDECK_DISABLE_LOCAL_AUTH commented out, with a note that uncommenting it and setting it to 0 requires login. If the container is reachable from outside your machine, that default deserves a second look before you expose port 3001.

### Which models does PilotDeck's Smart Routing send work to?

The README states that complex calls go to flagship models such as Claude 3.5 Sonnet or GPT-4o while simpler ones drop to lighter models, and that the router detects task difficulty automatically. It does not document the classification rules, so the routing decision is not predictable from the documentation alone.

## Sources

- [License: AGPL-3.0](https://github.com/OpenBMB/PilotDeck/blob/main/LICENSE)
- [OpenBMB/PilotDeck on GitHub](https://github.com/OpenBMB/PilotDeck)
- [Project website](https://pilotdeck.openbmb.cn)
- [README](https://github.com/OpenBMB/PilotDeck/blob/main/README.md)
- [Releases](https://github.com/OpenBMB/PilotDeck/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openbmb-pilotdeck