A local-first, Pi-powered AI agent workspace for Desktop and WebUI.
Download · Documentation · 中文文档 · Build from source
Bitlab is an open-source, local-first AI agent workspace for anyone who wants more control over their AI work. Download and use it through Desktop or WebUI, or extend its open-source foundation to build your own desktop agent product. Powered by the Pi agent runtime, it combines persistent local workspaces, model flexibility, browser tools, and document tools in one application. Application state stays under your local data directory, and credentials are stored through the operating system credential manager.
Follow the agent's progress, inspect file operations, and preview finished results directly inside the session.
Connect external tools Manage MCP servers, available tools, and connection status from one workspace. |
Reuse the way you work Browse and enable Skills that package instructions, scripts, and references. |
- Local-first workspaces — keep sessions, files, settings, and workspace history on your machine.
- Flexible model connections — sign in with ChatGPT Plus, use API keys for providers such as OpenAI or Anthropic (Claude), connect compatible endpoints, or run local Ollama models.
- Desktop and WebUI — work through the Electron app or a browser-based renderer backed by an RPC command-line client backed by the same runtime.
- Agent workflows — create and branch sessions, build plans, use Skills, resume work, manage follow-ups, and run multiple windows.
- Built-in tools — browse the web, work with attachments, render Markdown and code, and inspect or transform common document formats.
- Explicit control — choose Explore, Ask, or Execute permission modes, configure a network proxy, and switch between English and Simplified Chinese.
Every release publishes installers for all three interfaces on the Releases page.
| Platform | File | Notes |
|---|---|---|
| macOS (Apple Silicon) | Bitlab-<version>-arm64.dmg |
M1 and later |
| macOS (Intel) | Bitlab-<version>-x64.dmg |
|
| Windows x64 | Bitlab-<version>-x64.exe |
per-user install, no administrator rights required |
| Linux x64 | Bitlab-<version>-x86_64.AppImage |
chmod +x then run |
| Headless server | Bitlab-server-<version>-<platform>-<arch>.tar.gz / .zip |
serves the WebUI and the RPC API |
Every release also ships SHA256SUMS. Verify a download before running it:
shasum -a 256 -c SHA256SUMS --ignore-missingSigning certificates are optional for this project, and a release built without
them is packaged ad-hoc on macOS and unsigned on Windows. Check SIGNING_STATUS.txt
in the release assets for the trust status of the version you downloaded.
macOS refuses ad-hoc-signed apps with "Bitlab is damaged and can't be opened". The quarantine attribute is the cause, not a corrupted download:
xattr -dr com.apple.quarantine /Applications/Bitlab.appWindows SmartScreen: choose More info → Run anyway.
Maintainers configuring signing should read code-signing.md.
- Bun — Workspace runtime, package manager, scripts, and tests.
- Electron — Cross-platform desktop application shell.
- React and TypeScript — Shared user interface and typed application code.
- Vite and Tailwind CSS — Renderer tooling and styling.
- Pi — Agent runtime, model providers, sessions, and tool execution.
| Interface | Best for | Command |
|---|---|---|
| Desktop | Full local experience and browser pane | bun run electron:dev |
| WebUI | Browser access to the headless server | bun run server:prod |
- Bun 1.3.14 or later
- Node.js 18 or later
- Git
- Python 3.12 and
uvfor the complete document-tool test suite
git clone https://github.com/limboinf/bitlab-agent.git
cd bitlab-agent
bun install --frozen-lockfile
bun run electron:devBitlab creates its default workspace at ~/.bitlab/workspaces/default. The configuration root can
be isolated for development or testing with BITLAB_CONFIG_DIR=/path/to/directory.
| Command | Description |
|---|---|
bun run electron:dev |
Start the Electron development environment |
bun run electron:start |
Build and launch Electron once |
bun run server:prod |
Build and start the headless server with WebUI |
bun run test |
Run unit and isolated tests |
bun run validate:ci |
Run the full type, test, document-tool, and localization gate |
More commands and environment variables are documented in the development guide.
Bitlab is a Bun workspace with a shared runtime and renderer across its three interfaces:
apps/
electron/ Electron main, preload, renderer, and Browser pane
webui/ Browser adapter for the shared renderer
cli/ RPC command-line client
packages/
core/ Stable DTOs, events, and error contracts
shared/ Configuration, credentials, prompts, Skills, theme, and i18n
ui/ Shared React UI and content renderers
server-core/ RPC transport, sessions, and runtime orchestration
server/ Headless server
pi-agent-server/ Pi agent subprocess
session-tools-core/ Plans, Skills, browser, and session tools
Read the architecture guide for runtime boundaries, process ownership, and data flow.
The complete documentation is available in English and Simplified Chinese.
| Area | Guides |
|---|---|
| Start here | Development, architecture, testing |
| Models | Connections, Ollama |
| Work | Sessions, Skills |
| Tools | Browser, attachments, document tools |
| Runtime | permissions, network proxy |
| Project | features, releases, code signing, upstream synchronization |
| Contributing | CONTRIBUTING.md, SECURITY.md, CHANGELOG.md |
Bitlab started from selected architecture and code in
Craft Agents OSS v0.11.2
(a60ebc1a5a7c) and continues with an independent Git history and product boundary. Bitlab is not
affiliated with or endorsed by the upstream project. See NOTICE for attribution and the
comparison guide for the current differences.
Licensed under the Apache License 2.0. You may use, modify, and distribute the code, including for commercial purposes, subject to the license terms.