Admin / operator guide

From the Burrow™ specification set.

Admin / operator guide

This guide is for someone running Burrow™ on a Mac or publishing the Next.js site. It does not grant remote filesystem access. The hosted UI cannot call 127.0.0.1.

Safety Level 0

The engine is inventory-only. Allowed: enumerate directories, read metadata, hash file bytes, persist application metadata. Forbidden: copy, move, rename, delete, metadata mutation, and cloud-state mutation.

Releases 0.1 and 0.2 keep SafetyGate at Level 0. Mutation requests are denied and recorded in memory. Do not expose production filesystem mutation capability.

See 03 — Safety Model.

Hosted UI cannot see the Mac

Environment Hostname Engine reachability
Local http://localhost:3000 Can query loopback when the engine is running
Preview burrow-dev.jasonkoch.io Disconnected. Mixed content blocks http://127.0.0.1.
Production burrow.jasonkoch.io Disconnected. Same as preview.

The Vercel project slug is vault. Do not set the engine secret on Vercel. A public HTTPS site must not hold a loopback credential.

Run the engine locally

From the repository:

cd engine/Burrow
swift run Burrow

The process binds 127.0.0.1 only (never 0.0.0.0) on port 8741 by default and prints the listen URL.

swift run Burrow --port 8741
swift run Burrow --port 0    # ephemeral port
BURROW_ENGINE_SECRET=replace-me swift run Burrow --port 8741
swift run Burrow --secret replace-me

Allowed HTTP surface (all require the secret):

  • GET /health
  • GET /identity

There are no copy, move, rename, delete, archive, or backup routes.

curl -H "X-Burrow-Secret: $BURROW_ENGINE_SECRET" http://127.0.0.1:8741/health
curl -H "X-Burrow-Secret: $BURROW_ENGINE_SECRET" http://127.0.0.1:8741/identity

Requests without the header, or with the wrong value, return HTTP 401.

Secrets

Role Current name Legacy name still accepted
Engine process env BURROW_ENGINE_SECRET PLATYPUSVAULT_ENGINE_SECRET
HTTP header X-Burrow-Secret X-PlatypusVault-Secret
Next.js local UI NEXT_PUBLIC_BURROW_ENGINE_SECRET NEXT_PUBLIC_PLATYPUSVAULT_ENGINE_SECRET
Engine port (UI) NEXT_PUBLIC_BURROW_ENGINE_PORT NEXT_PUBLIC_PLATYPUSVAULT_ENGINE_PORT

Copy apps/web/.env.example to apps/web/.env.local for localhost only. Match the value the engine printed or received. Never commit .env.local. Never put that value on Vercel.

Catalog location

The SQLite catalog is application metadata, not user documents.

Default path:

~/Library/Application Support/Burrow/catalog.sqlite

If a legacy ~/Library/Application Support/PlatypusVault/catalog.sqlite exists and Burrow™ has not been created yet, that file is reused so local databases are not orphaned.

The catalog must never live in Documents, iCloud Drive, or OneDrive. Catalog writes do not modify user files. The filesystem wins on rescan.

Run the website locally

cd apps/web
npm install
npm run dev

Open http://localhost:3000. / is the product site. /dashboard is the console. /docs is this portal.

Root quality commands: make lint, make typecheck, make test, make build.

Site environment variables

These are site identity only. They are not the engine secret.

Variable Local Preview Production
NEXT_PUBLIC_SITE_ENV local preview production
NEXT_PUBLIC_SITE_URL http://localhost:3000 https://burrow-dev.jasonkoch.io https://burrow.jasonkoch.io

If those are unset, VERCEL_ENV selects preview vs production; everything else is local.

Domains

Retired hostnames vault.jasonkoch.io and vault-dev.jasonkoch.io are no longer assigned. If a new subdomain does not resolve, add a Cloudflare CNAME to cname.vercel-dns.com.

See Hosting.