docs · quickstart

Quickstart: self-host your AI coding agents

Install CodeCave, start it, and have a fleet of AI coding agents working a board on your own machine. Two commands and a browser wizard — the rest of this page is what to do once it is running.

npm i -g @codecave-ai/codecave

Requirements

Short list. If you already write code on this machine, you almost certainly have most of it.

macOS or Linux: Windows works through WSL2. There is no Windows-native build.
Node.js 22 or later: CodeCave installs from npm and runs as a Node process.
git: Every run works in its own git worktree and branch in your repository.
Claude Code or Codex: You bring your own model access. Install at least one harness and sign in — a Claude subscription or API key for Claude Code, an OpenAI account for Codex.
An activation key: Emailed to you. Setup asks for it once, and it is checked on your machine.
gh (optional): The GitHub CLI. If you turn on automatic push for a project, it opens a pull request for each finished run.

Install and first run

No database to provision. CodeCave keeps everything in a single local SQLite file under ~/.codecave/.

Install the CLI
npm i -g @codecave-ai/codecave
A global install, so codecave is on your PATH.
Start it
codecave start
It boots, applies any migrations, and prints a one-time setup link. By default it binds to 127.0.0.1 — nothing on your network can reach it yet.
Open the URL and finish setup
The browser wizard runs once: it takes your activation key, creates your admin account, checks that your agent harness is installed and signed in, and creates your first project by pointing at a local git repository.
From there: add a task to the board, run an agent on it, and watch the run console. Something missing? codecave doctor tells you what and how to fix it.

terminal

$ npm i -g @codecave-ai/codecave
$ codecave start

  codecave
  db      ready   ~/.codecave/
  harness ready   claude code
  setup   required

  open http://127.0.0.1:… ▍

Illustrative output. Your port and paths will differ.

Core concepts

Six nouns. Learn these and the rest of the product explains itself.

Projects

A workspace pointed at a local git repository path. Members and permissions are scoped per project, so client work stays separated.

Tasks & the board

Kanban columns — Backlog, To Do, In Progress, Testing, Needs Input, Done — that you can rename and reorder. When an agent is stuck it asks on the task; you reply and press Resume. Each task’s Code tab shows the diff and merges it as one commit.

Agents

A persona + a harness + permissions: name, system prompt, Claude Code or Codex, model, reasoning effort, permission mode, budget cap and timeout. They live in a global catalog and are reusable across every project.

Squads

An ordered team of agents that work one task relay-style — each builds on the last one’s committed work, in one shared worktree and branch. A Squad pauses if a step is blocked or fails, and you resume it from that step.

Column automations

Give a column a rule: when a task lands here, start this Squad. Rules declare on-success and on-failure destinations, so a finishing Squad routes the task onward and the next column’s rule fires. That is autopilot — the board is the state machine.

Guard rails

Per-project caps on revisits, total hops and cost. Trip one and the task parks in Needs Input with a notification. A run that changed nothing parks there too, instead of being passed along as a success.

The safety machinery is covered properly on Security & privacy.

CLI reference

Every command, one line each. If you use --data-dir, pass it to every command.

$ codecave start: Starts CodeCave and prints the URL to open. On a fresh install it prints a one-time setup link instead. Plain codecave does the same.
$ codecave stop: Stops a running CodeCave.
$ codecave status: Whether it is running, and its port, address, data folder and version.
$ codecave service install: Runs CodeCave in the background when you log in — launchd on macOS, systemd on Linux. Also uninstall and status.
$ codecave doctor: Checks Node, git, the database module, the data folder, and your agent harnesses (Claude Code, Codex) including their sign-in. Run this first when something is wrong.
$ codecave selftest: Starts a throwaway install and proves it works end to end.
$ codecave backup: Saves the database and config.json to ~/.codecave/backups.
$ codecave backups: Lists saved backups, newest first.
$ codecave restore: Restores a backup — pick one from a list, or pass a file. Stop CodeCave first; your current state is saved before it is replaced. Moving machines is a backup, a copy and a restore.
$ codecave reset: Erases everything except backups and returns to first-run setup. Offers a backup first and asks you to type reset.
$ codecave reset-admin: Locked out? Sets a new password for an admin account and signs it out everywhere. Run it on the machine CodeCave is installed on.
$ codecave seed-agents: Adds back any default agents that are missing. Changes nothing else.

Options

--port <n>: Port to listen on. Default 3737.
--host <address>: Address to bind. Default 127.0.0.1.
--data-dir <path>: Where data and config live. Default ~/.codecave.
--web: Bind 0.0.0.0 so other devices can reach it.

Flags apply to that run only; to keep a port, set it in ~/.codecave/config.json. Run codecave --help for the version you have installed — the CLI is the authority, not this page.

Web mode and tunnels

CodeCave is local by default. If you want to reach your instance from another machine — or share it with a teammate — turn on web mode and put a tunnel in front of it.

ngrok and Cloudflare tunnels are both supported. Exposure is deliberate, and it is gated: CodeCave refuses to turn on web mode until an account with a password exists. Set one first — there is no flag to talk it out of this.

before you expose it

Set a password on your account. Web mode will not turn on without one.
Review who has terminal.access and run.execute — both are code execution on the host.
Remember the instance is your machine. A tunnel points the internet at it.

note

This is a quickstart, not the full manual.

It covers install, first run and the vocabulary. For anything past that, codecave --help is the authority on the CLI — it ships with your install, so it can never drift from the version you are actually running. Anything it does not answer, ask us.

Ask a question