Install Cabinet
Get from zero to a running cabinet in under five minutes. The first-run wizard creates your data folder, seeds an example cabinet, and asks you to plug in one model API key.
Who this is for
You want a local-first knowledge base where every page is a markdown file on disk and a team of AI agents can edit and run jobs against it.
If you're brand new, read Philosophy first — it's the 90-second pitch.
Supported systems
| System | Status | Notes |
|---|---|---|
| macOS 12+ | Fully supported | Native Electron app or npx CLI. Apple Silicon and Intel. |
| Linux | Untested | Should work via the npx CLI (Cabinet is Node + Electron — both fully Linux-compatible) but hasn't been verified yet. Try it and share what breaks. |
| Windows | Via WSL2 | Run inside WSL2 (Ubuntu recommended). Native Windows support is on the roadmap. |
| Requirement | Version | How to check |
|---|---|---|
| Node.js | 22+ (LTS) | node -v — repo ships an .nvmrc, run nvm use to auto-switch |
| git | any recent | git --version |
| An AI CLI | latest | One of: Claude Code, Codex CLI. See Bring your own AI. |
Install — Mac native app (Electron)
Easiest path on macOS. Download the .dmg, drag Cabinet into Applications, double-click. No terminal required.
→ Download Cabinet for Mac (.dmg)
Both Apple Silicon (M-series) and Intel builds are published with each GitHub Release. The first launch asks for the same things the CLI does — a folder for your cabinets, and an AI provider.
Note. macOS may ask you to confirm the app on first open (Apple Gatekeeper). Right-click → Open if you see "unidentified developer."
Install — npx CLI (any platform)
npx create-cabinet@latest my-cabinet
cd my-cabinet
npm run dev:all
Open the URL printed in your terminal (usually http://localhost:4000). The wizard creates a data folder, seeds an example cabinet, and prompts for one model API key.
Tip. Cabinets live anywhere on disk. Set
CABINET_DATA_DIR=/path/to/folderbeforenpm run dev:allto use a different location. Your folder is your data; the app is just a viewer.
Pick a model provider
Cabinet is bring-your-own-AI. You connect the providers you already pay for. There's no Cabinet middleman, no inference markup, no quota.
| Provider | Best for | Get a key |
|---|---|---|
| Anthropic Claude | Default for most agents — long context, careful writing | console.anthropic.com |
| OpenAI GPT | Cheap routing, strong tool use, fast | platform.openai.com |
| Google Gemini | Long-context research, low cost per token | aistudio.google.com |
| xAI Grok | Latest news, code, lighter-weight tasks | console.x.ai |
| Local (Ollama / LM Studio) | Offline, private, no API bill | ollama.com / lmstudio.ai |
You can connect multiple providers and pick a default per agent or override per task.
Verify it worked
Three checks. If any fail, jump to common failure modes below.
- The sidebar shows
index.mdselected. - Press ⌘K (or Ctrl+K) — search opens.
- Press ⌘⇧A — the AI panel opens on the right.
If all three pass, your cabinet is alive. Now go meet your team.
Try your first agent
Open .agents/ in the sidebar. Click any persona. Click Hire. The agent appears in your AI team panel with the Active dot lit. Click their avatar to chat with them, or assign a task on the Task Board.
Don't have a team yet? Templates ship complete teams in one command:
npx cabinets add cabinet-app/job-hunt-hq
# or browse the registry at cabinets.sh
Common failure modes
| Symptom | Likely cause | Fix |
|---|---|---|
EADDRINUSE :3000 | Old dev server still bound | lsof -i :3000 then kill the PID, or set PORT=3001 |
| Blank editor on first load | Model API key missing or invalid | Open Settings → Providers, paste your key, refresh |
npm ERR! 401 on install | Stale auth token in ~/.npmrc | npm config delete _authToken, then retry |
| Sidebar says "no cabinets" | CABINET_DATA_DIR points at an empty folder | Unset it, or run npx cabinetai create inside it |
| Agent says "no API key" mid-chat | Provider keyed but model not allowed | Settings → Providers → enable specific models |
| First-run wizard hangs | Firewall blocks fonts.googleapis.com | Allow it, or use the offline build (npm run dev:offline) |
Recovery toolkit
When things look broken, run these in order:
npx cabinetai doctor # Diagnose env, ports, providers, db
npx cabinetai sessions list # Show active sessions and locks
npx cabinetai uninstall # Remove cached app (your data is safe)
npx cabinetai update # Reinstall the latest version
Your cabinet folders are your data. uninstall only removes the cached app — it never touches your ~/cabinets/ folders.
Quick reference
| Command | What it does |
|---|---|
npx create-cabinet@latest | Scaffold a new cabinet folder and start the app |
npx cabinetai run | Start Cabinet against the current folder |
npx cabinetai create <name> | Create a new cabinet inside this one |
npx cabinetai add <owner/repo> | Install a template cabinet from cabinets.sh |
npx cabinetai doctor | Diagnose install + provider issues |
npx cabinetai update | Reinstall the latest version |
npx cabinetai uninstall | Remove cached app (keeps your data) |
| ⌘K | Open search |
| ⌘⇧A | Toggle AI panel |
| ⌘` | Toggle web terminal |
| ? | Open keyboard cheat sheet |
See the full CLI reference for every flag and exit code.
Next steps
- Meet your AI team — what personas, heartbeats, and routines actually are.
- Browse template cabinets ↗ — start with a pre-built team for your job.
- Showcase — see the agents workspace and task board live.
- Tips and best practices — the small habits that compound.