security · privacy
Your code stays on your machine.
CodeCave is self-hosted, and that is not a marketing position — it is the whole architecture. This page is the specific version: where your data sits, how runs are isolated, who can do what, and the parts we don’t pretend to solve.
One boundary, and it’s your box
CodeCave installs from npm and runs as a process on your own hardware. It points at git repositories that are already on disk. There is no upload step, no sync, no account to create — because there is nowhere else for anything to go.
your machine
your git repos
read and written in place
codecave
the web app + SQLite
the agent
Claude Code, running locally
the agent’s API call to your model provider
The only outbound traffic. It carries the prompt and whatever code context the agent chose to send — which is the one place your code leaves the box.
The one thing that does leave is the agent’s call to your model provider, using the Claude subscription or API key you already have. That relationship is yours, not ours — we are not in the middle of it, and we never see it.
Storage: one file, on your disk
Tasks, projects, agents, runs, costs, users — all of it lives in a single local SQLite file under ~/.codecave/.
database
No database to run
No Postgres to provision, no Redis, no external service credentials to rotate. One file you can back up, move, or delete.
account
No cloud account
There is nothing to sign up for. CodeCave does not phone home, and it has no server-side component that we operate.
portability
backup / restore
The CLI ships backup and restore commands. Your instance is a directory — treat it like one.
Agents work in isolation, and hand you a PR
The riskiest thing an autonomous agent can do is write to your working tree. CodeCave simply never lets it.
- A fresh git worktree per run. Every run gets its own worktree on a new branch. Nothing an agent does can collide with what you have open in your editor.
- Commits go to that branch. The work accumulates as real commits you can read, diff, and blame — not as a pile of unexplained edits.
- A pull request, via gh. When the run finishes, CodeCave opens a PR using the
ghCLI. No remote configured? It leaves the branch for you and says so. - main is never touched by an agent. Merging stays a human decision. A Squad relays through one shared worktree and branch and still produces exactly one PR.
Access control that names the dangerous parts
CodeCave is multi-user from the start: global roles, project roles, custom roles you define, and per-project membership.
Most permissions are boring — read a board, create a task, run an agent on one project. Two are not, and CodeCave says so out loud rather than burying them in a checkbox list.
Terminal access and run execution are remote code execution as the server user. An agent run executes commands on the host; a browser terminal session is a shell on the host. Both are flagged as dangerous in the UI and neither is on by default. Grant them to people you would already give SSH to.
API keys are hashed at rest, scoped, and expiring. Runs authenticate with ephemeral keys, so a key that leaks out of a log is a key that has already stopped working.
projects.readsafetasks.writesafeagents.manageadminruns.executeRCE as server userterminal.accessRCE as server user
Illustrative. Dangerous permissions are labelled in the product too — never colour alone.
Guard rails, cost caps, and no fake success
Autonomy is only safe if it has a floor. Per project, you cap how far a task can go and how much it can spend.
cap
Revisit cap
The maximum number of times a task may re-enter the same column. Loops end.
cap
Total-hops cap
The ceiling on how many moves a task can make across the whole board before a human looks at it.
cap
Cost budget
A spend limit per task. Cost is tracked per run, per Squad and per project, so the number is not a guess.
guard
No-op guard
A run that exits cleanly but committed nothing is reported as a no-op — never as a success.
Trip any cap and the task parks in Needs Input and a human gets notified. It does not retry forever, and it does not fail silently. Any human board move resets the counters.
Local by default; exposed only on purpose
CodeCave binds to 127.0.0.1. Out of the box it is not reachable from your network, let alone the internet.
If you want to reach it from a phone, a second machine, or a teammate’s laptop, there is web mode plus a tunnel (ngrok or Cloudflare). That is a deliberate act, not a default.
And it is gated. CodeCave refuses to expose an instance that has no admin password set — the failure mode where someone tunnels a wide-open board to the public internet is one we decided to make impossible rather than document.
- allowedAdmin password set → web mode and tunnels available.
- refusedNo admin password → exposure is blocked outright.
what codecave does not do
The honest part
“Self-hosted” solves some problems and hands you others. Here is the list we would want to read before installing someone else’s software.
It runs code as the server user
Agents execute commands, and the terminal is a real shell. There is no container or VM boundary between a run and the rest of your machine. Worktree isolation protects your branches, not your filesystem. So who you grant terminal and run-execution permissions to is the security decision — everything else is downstream of it.
Your host is your responsibility
Disk encryption, OS patches, who has an account on the box, what your tunnel is pointed at, backups of ~/.codecave/ — all yours. We cannot secure a machine we have no access to, and the fact that we have no access to it is the point.
Your model provider still sees the prompts
“Your code never leaves your machine” means CodeCave never uploads your repository. It does not mean nothing is ever transmitted: the agent sends prompts and the code context it needs to your provider, under your account and their terms. Read those terms. That call is the boundary, and you own both ends of it.
Found something we got wrong, or a hole we haven’t? Tell us — we would rather hear it from you than read it later.