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 build
• pnpm 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

• Business model
• Architecture principles
• Debt reduction roadmap
• Cloud vs local workflows
• Responsive design (mobile/tablet)
• Postgres portability
• Local orchestration runtime

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:

1. 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.
2. 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.
3. 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.