Loki
Loki is an independent product for building and changing projects with AI
agents. Start with a brief, create a real repository, build and deploy, then use
project feedback to direct the next change. OrangeCat linking is optional;
an OrangeCat account is not required to build in Loki.
Org names and relationships come from bitbaum/fleet
and its registers. Hosting addresses are recorded in scripts/hetzner/apps.conf.
The product thesis is simple: AI agents are becoming cheap execution capacity,
but serious users still need a trustworthy command center. Loki provides the
state, queues, handoffs, guardrails, and business context around that capacity.
Production: https://loki.orangecat.ch
Status: beta, pre-1.0. Free while prices are not announced. Hosted on Hetzner.
What It Does
- Agent operations: launch, monitor, switch, and dispatch supported agents across real project workspaces.
- Hybrid control plane: hosted Next.js app owns auth, database, product UI,
and team state; an eligible cloud builder or connected Fleet Runner owns workspaces, shell, git, and agent CLIs.
- Project execution memory: per-project handoffs, queues, recent outcomes,
lifecycle signals, git state, and saved context are visible in one place.
- Beside the agents: Today, people, crew (humans you hand work to), goals,
habits, events and money live in the same workspace as the projects.
- Economy-aware: Loki pulls open demand from sibling product OrangeCat and
searches the economy by meaning (OrangeCat embeds the query server-side), so
finding what already exists and building what's missing is one flow.
- Operational trust: runtime signals are persisted, versioned, and
explained in the UI so users can tell the difference between active work,
an open terminal, and historical handoff context.
Product And Economic Model
Loki serves individual builders and teams. Optional OrangeCat links connect
build dossiers to public profiles and funding. Linking does not publish private
work: publishing requires a separate owner choice.
Designed economic model (planned monetization).
| Layer | Value | Planned monetization (not billed) |
|---|
| Individual builder | One Loki for projects, agents, commitments, and execution memory | Pro subscription (planned) |
| Team / studio | Shared project state, team visibility, agent dispatch, audit trail | Per-seat team plan (planned) |
| Agent runtime | Eligible accounts use the shared cloud builder; others can connect Fleet Runner on their computer | Paid runtime seats / usage tiers (planned) |
| Execution intelligence | Queue drain, health gates, outcomes, continuation policies | Premium automation tier (planned) |
| Enterprise / investor diligence | Operating telemetry, governance, security, and project health | Managed deployment / annual contract (planned) |
See docs/business-model.md for positioning,
pricing logic, expansion loops, and defensibility.
Architecture At A Glance
Hosted control plane (self-hosted Next.js on Hetzner, Caddy in front)
Auth, database, UI, team state, command queue, runtime snapshots
Execution runtime (eligible cloud builder or user machine)
Project workspaces, owned agent sessions, git, shell tools, runner
Data layer (Postgres / Drizzle)
User projects, runtime state, orchestration events, prompt queues,
goals, people, habits, events, billing, memories
Key design rules:
- SSOT first: schema, navigation, agent registry, runtime snapshots, prompt
queues, and design tokens each have one canonical owner.
- Cloud/local separation: browser workflows stay cloud-safe; shell and
terminal work routes through the authenticated builder for that project.
- Runtime truth beats assumptions: Control reflects recorded runs and current worker sessions. A queued prompt
or successful agent turn is not deployment evidence.
- Agent-agnostic direction: Claude-era compatibility remains where needed,
but adapters and registry definitions are the migration path.
Stack
- Next.js 16 App Router, React 19, TypeScript strict
- PostgreSQL 17 with Drizzle ORM and schema-inferred types
- NextAuth v5: OrangeCat (OIDC, the primary account), GitHub, Google and X
OAuth, plus email/password and local owner-key support for private installs
- Tailwind CSS 4 with a tokenized dark-first design system
- Builder-owned agent sessions for terminal runtime control
- Self-hosted on Hetzner (
bitbaum box, Caddy + systemd) — production deploys run in the Deploy workflow (.github/workflows/deploy.yml) after CI is green on main, which calls scripts/deploy-hetzner.sh; cron jobs run on the box
- Husky + GitHub Actions for type, lint, and audit checks
Repository Map
src/app/ App routes and API endpoints
src/components/control/ Agent operations UI
src/components/*/ Domain surfaces: today, people, projects, goals, etc.
src/config/ Navigation, prompts, categories, product constants
src/db/schema/ Drizzle schema SSOT
src/db/queries/ Data access by domain
src/lib/ Runtime, auth, orchestration, formatting, utilities
home/ Orchestration library and runtime tests
scripts/ Build, deployment, smoke, migration, and verification tools
docs/ Architecture, business model, cloud/local workflows
drizzle/ Generated schema migrations
packages/agent/ Hosted installer CLI
content/ Public essays and whitepaper content
Quality Bar
Every change should preserve:
pnpm run verify — the one canonical gate. CI runs it verbatim, so green
local verify means green CI. Its step list lives in package.json
(scripts.verify); this file deliberately does not restate it.pnpm run buildpnpm run smoke
This used to enumerate an ad-hoc subset of test scripts. Every such list
drifts from the real gate — three docs ended up teaching three different,
all-weaker bars — so the rule is now: name the gate, never its contents.
CI runs type/lint/design/self-test checks on pushes and pull requests. A
scheduled audit workflow fails on high or critical dependency vulnerabilities.
Production deploys to the Hetzner box run in the Deploy workflow after CI is
green on main (or when the auto-merge sweep reconciles it), which calls
scripts/deploy-hetzner.sh (rsync → restart loki-app).
Local Development
pnpm install
docker compose up db -d
cp .env.example .env.local
pnpm run db:push # local scratch DB only — never a shared/prod database
pnpm run dev
Minimum local .env.local:
DATABASE_URL=postgresql://loki:changeme@localhost:5432/loki
AUTH_SECRET=replace-me
AUTH_TRUST_HOST=true # without it every /api/auth/session returns 500
GITHUB_CLIENT_ID=replace-me
GITHUB_CLIENT_SECRET=replace-me
AUTH_TRUST_HOST is not optional on localhost: Auth.js rejects an untrusted
host, so the pages render but nothing can read a session. It is compared to the
exact string "true" — 1 does not work.
The database needs the pgvector extension (the knowledge index stores a
vector(384)); drizzle-kit push fails on the first table without it. The
compose db service uses the pgvector/pgvector image and creates the extension
on first boot. Against your own Postgres, run CREATE EXTENSION vector; first.
On a fresh database, visit /setup to create the first user.
Agent Runtime
Work runs on the cloud builder by default; a project runs on your computer
when its profile says so ("Runs on" in Control) or when its checkout exists
only there. Shared cloud building is restricted to eligible accounts, so other
accounts need a connected Fleet Runner; see src/lib/execution-access.ts. To
connect your machine:
curl -fsSL https://loki.orangecat.ch/api/agent/install | node - init --base-url https://loki.orangecat.ch
The runtime requires at least one supported agent CLI on the selected builder:
claude, codex, gemini (shown as Antigravity), agent (Cursor), grok,
or openclaw.
See docs/development/cloud-local-workflows.md
for the full matrix of browser-only vs local-runtime workflows.
Run your own copy
Loki is MIT. A copy runs anywhere Docker runs, and nothing points at bitbaum's
infrastructure that an environment variable cannot repoint.
git clone https://github.com/bitbaum/loki && cd loki
cp .env.example .env.local # fill DATABASE_URL, AUTH_SECRET, AUTH_TRUST_HOST=true
docker compose up -d # pgvector Postgres, schema, the app on :3000
Then open /setup to create the first user. From there:
- Your hostname:
NEXT_PUBLIC_APP_DOMAIN (and NEXTAUTH_URL). Callbacks,
emails and copy build on it (src/config/brand.ts); loki.orangecat.ch is
only the fallback.
- OrangeCat is optional:
NEXT_PUBLIC_ORANGECAT_URL points links at your
own copy or stays unset; sign-in works with GitHub or e-mail alone.
- Agents run on your machine via the Fleet Runner (
desktop/) or on any
box you give the runner script; the Hetzner builder is bitbaum's, not a
requirement.
- The contract is
.env.example: every variable src/ reads is named
there with the file that reads it, and scripts/test/env-example-covers-src.ts
fails CI when one is not. A feature whose key is empty is off, not broken.
The Loki name and visual identity are not part of the licence; a copy should
carry its own (src/config/brand.ts is one file).
Important Docs
Security And Operations
- Secrets stay out of Git; use
.env.example as the contract.
- Production uses direct and pooled Postgres URLs separately.
- Fleet Runner and builder access use per-user
ck_* agent tokens.
- Legacy daemon tokens remain accepted only behind an explicit server-side opt-in flag.
- Private surfaces can be PIN-gated server-side.
- Dependency audit runs daily and high+ findings block the audit workflow.
See SECURITY.md for reporting and operational expectations.
Take it
Bitbaum is a platform for the new economy and for creation: building,
engineering and researching. It's a community of builders, creators and
researchers, and of the people who support them. We work as engineers in the
loop: agents do much of the typing, and people own the judgement.
This code is MIT-licensed so that you can take it. Use it, fork it, rebrand it,
sell it, or lift a single file. Make it yours and keep improving it the way you
like. You don't need to ask, book a call or sign a CLA. Just keep the
LICENSE with your copy.
npx degit bitbaum/loki my-loki # a clean copy without our git history
cd my-loki && pnpm install
- Needs: Postgres with pgvector and a GitHub OAuth app (see Local Development).
- Make it yours: the name, colours and contact details start in
src/config/brand.ts.
- Shared pieces: the
@bitbaum/* kits install from public npm or public GitHub, so you need no tokens or private registry.
The Loki name and logo are not covered by the licence, so ship your copy under a name of your own.
More to take: orangecat.ch/steal and github.com/bitbaum.
Want to build it with us? Show us how you think
Copying code is free. What stays scarce once agents and robots write most of
it is seeing the whole system. Pick one of these, in this repo, and open an
issue or a pull request:
- Find the second source of truth. Find a fact this code defines in two
places. Show how the copies will drift, and say where the one copy should
live.
- Find the silent failure. Pick a promise this system makes. Find where it
fails while every check stays green, and propose the check that would catch
it.
- Find where the human belongs. Point to a step where an agent acts alone
but a person should decide, or the reverse, and say why.
A real one from this repo: in August 2026 three PRs merged onto a green main and none of them deployed, because a run started with the default GITHUB_TOKEN wakes nothing downstream. Every check was green. Find the next promise that fails like that.
A short, correct answer beats a long one, and so does an answer that admits
what it doesn't know.
