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

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: CodeCave installs from npm and runs as a Node process.
A Claude subscription or API key: You bring your own model access. The shipped harness is Claude Code — sign in with your subscription or supply an API key.
gh (optional): The GitHub CLI. With it, finished runs open a pull request automatically. Without it, they leave you the branch.

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
A global install, so codecave is on your PATH.
Start it
codecave start
It boots, applies any migrations, and prints a local URL. 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 and does three things: creates your admin account, checks that your agent harness is present and can talk to Claude, 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.

terminal

$ npm i -g 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 with lifecycle statuses — backlog, ready, in progress, testing, needs input, done. The board is where work is queued and where it lives.

Agents

A persona + a model + permissions: name, description, system prompt, 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, producing one PR. A Squad pauses if a step is blocked or fails, and you resume it.

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 committed nothing is reported as a no-op, never as success.

The safety machinery is covered properly on Security & privacy.

CLI reference

The whole surface. One line each, no flags invented.

$ codecave start: Starts the server and prints the URL to open. On a fresh install this is also where the browser setup wizard begins.
$ codecave doctor: Checks the environment: Node, git, the agent harness, and whether gh is available for pull requests. Run this first when something is wrong.
$ codecave reset-admin: Recovers the admin account from the machine itself, for when you are locked out of your own instance.
$ codecave service: Installs CodeCave as a background service — launchd on macOS, systemd on Linux — so it comes back after a reboot.
$ codecave backup: Takes a copy of your instance: the single SQLite database under ~/.codecave/.
$ codecave restore: Puts a backup back. Moving to a new machine is a backup, a copy, and a restore.

Run any of these with --help for the current options — 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 expose an instance that has no admin password set. Set one first — there is no flag to talk it out of this.

before you expose it

Set an admin password. Web mode will not start without one.
Review who has terminal.access and runs.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