docs / self-hosting

Self-hosting

Run krabs on your own box. You get the HTTP API, the CLI, and the audit log — fully under your control. No multi-tenancy, no billing, no web dashboard. Those live only in the hosted product.

Intro

The self-host image runs only the standalone Hono API server (src/api/server.ts). The Next.js dashboard at app.krabs.dev is hosted-only — it depends on Clerk, Polar, and infra we do not ship in the image. Everything an agent actually needs (the contract, the operations, the audit log, the CLI, MCP via the proxy) works identically against a self-hosted node.

self-host parity
Same on both: the API contract at /v1/*, the CLI surface, the schema endpoint, the audit log, the idempotency keys. Different: no web dashboard, no device login flow (use the bootstrap API key directly), no Polar billing, no Clerk users — a self-host install is single-tenant.

Prerequisites

  • Node 22+ — set in engines.node.
  • pnpm 9+ — used to install and to run pnpm setup once.
  • Docker — optional, recommended if you do not want to manage Node yourself.
  • Disk — about 50 MB for code, plus roughly 1 MB of SQLite per 10k records.

Option A — Docker

The shortest path. Three commands plus one host-side setup step:

git clone https://github.com/augusto-devingcc/krabs.git
cd krabs
cp .env.example .env
pnpm install
DATABASE_URL=file:./data/krabs.db pnpm setup
docker compose up -d

pnpm setup runs on the host against the same SQLite file the container will mount (./data/krabs.db). It creates the local account, runs migrations, and prints a bootstrap API key. Save the key — you will not see it again.

The volume mount in docker-compose.yml binds ./data on the host to /app/data in the container, so the SQLite file is durable across restarts. Backups reduce to copying ./data/krabs.db.

Port mapping defaults to 3000:3000. Override with KRABS_PORT:

KRABS_PORT=8088 docker compose up -d
run setup on the host, not inside the container
pnpm setup is interactive and writes the bootstrap key to your terminal. Running it on the host against the volume-mounted SQLite file is simpler than execing into the container. The container itself only runs migrations on boot and starts the API.

Option B — Node

For developers who already have a Node toolchain. No Docker required.

git clone https://github.com/augusto-devingcc/krabs.git
cd krabs
cp .env.example .env
pnpm install
pnpm setup
pnpm dev:api

pnpm dev:api runs the Hono server under tsx watch on http://localhost:3000. For a production-style run without watch:

node --import tsx src/api/server.ts

Using the CLI

pnpm setup already saved your bootstrap token. Verify with:

krabs auth status

By default the CLI points at the hosted endpoint. For self-host, point it at your local server:

export KRABS_API_URL=http://localhost:3000

# or, persist it in the CLI config:
krabs auth login --token <your-bootstrap-key> --api-url http://localhost:3000

Using the API

The API is plain HTTP. Every operation is documented at /v1/schema:

curl http://localhost:3000/v1/schema | jq '.operations[].operation' | head

Pass your bootstrap key as a bearer token on every other route:

curl http://localhost:3000/v1/me \
  -H "Authorization: Bearer $KRABS_API_KEY"

Agents

Drop the agent skill into your Claude config:

mkdir -p ~/.claude/skills/krabs
curl -fsSL https://krabs.dev/skill.md -o ~/.claude/skills/krabs/SKILL.md

The skill is portable: it describes the contract, not the deployment. The same skill.md works against a hosted node and a self-hosted node — point the CLI or MCP proxy at whichever URL you run.

Limitations

Self-host v1 ships the API and CLI. It does not ship:

  • The web dashboard at app.krabs.dev (Next.js + Clerk).
  • The device-flow login (krabs auth login via browser). Use the bootstrap key directly.
  • Polar billing — there are no plans, no quotas, no metering.
  • Clerk users — a self-host install is single-tenant, one account, one set of keys.

If you want any of those, use the hosted version at app.krabs.dev.

Backups

SQLite makes backups trivial. Use the online .backup command so writers do not block:

# one-shot snapshot
sqlite3 ./data/krabs.db ".backup './data/krabs-$(date +%F).db'"

# nightly via cron (2 AM)
0 2 * * * sqlite3 /srv/krabs/data/krabs.db ".backup '/srv/krabs/backups/krabs-$(date +\%F).db'"

Restore is a file copy. Stop the container, replace ./data/krabs.db, start it again.

Upgrading

Pull, install, migrate, rebuild:

git pull
pnpm install
pnpm db:migrate
docker compose up -d --build

Migrations are additive-only. There is no automated rollback — to roll back, restore the pre-upgrade ./data/krabs.db snapshot and check out the previous git tag.

Next steps

Edit this page on GitHub →last updated 2026-05-16 · v0.4.3