Self-hosting

krabs is self-host only. You run it on your own box: the HTTP API, the CLI, the MCP server, and the audit log — fully under your control. No login, no billing, no web dashboard, single account.

Intro

krabs runs the standalone Hono API server (src/api/server.ts), which also mounts the MCP server. Everything an agent needs — the contract, the operations, the audit log, the CLI, MCP — works against your node.

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

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

Point the CLI 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.

What it is not

krabs ships the API, the CLI, and the MCP server. By design it has no:

• Web dashboard — agents operate it; there is no human UI.
• Login or user accounts — single account, authenticate with the bootstrap API key.
• Billing — no plans, no quotas, no metering. It is free and open source (MIT).
• Multi-tenancy — one install, one account, one set of keys.

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

• Quickstart → — same flow, against your own server.
• The contract → — the five properties every operation honors, hosted or self-hosted.