asklokesh/loki-mode repository overview

⁠Loki Mode

Multi-agent autonomous development system. Takes a spec to a deployed product with minimal human intervention.

Transform your spec into a fully built, production-ready product. Built on 2025 research from OpenAI, Google DeepMind, and Anthropic. Source-available under BUSL-1.1.

The image ships the Claude Code CLI pre-installed, so it can run real builds out of the box. Just supply credentials (see Authentication below).

Docker is where sandboxes and runs happen. loki docker gives you the full local experience in one command (including .loki/ state, resume, and continuity), so start there. The raw docker run and docker compose methods below remain available as alternatives.

⁠Quick Start (loki docker, easiest)

If you already have loki installed on the host (npm/brew/bun) plus Docker, loki docker is the simplest way to run loki in a container. It is a thin host wrapper around the published image: it runs any loki command inside asklokesh/loki-mode with zero config.

# Run a build against a spec in the current directory
loki docker start prd.md

# Any loki command works
loki docker status

# Print the docker command it would run, without running it
loki docker --dry-run start prd.md

What it does for you automatically:

• Bind-mounts the current folder to /workspace, so .loki/ state (memory, session, queue, checkpoints) persists on the host. Resume and continuity behave exactly like the local loki CLI. Stop a build and run loki docker start prd.md again later and it resumes with full memory and session continuity.
• Auto-detects auth, in this order:
  1. ANTHROPIC_API_KEY if set in your environment (explicit), else
  2. your host's existing Claude Code login (macOS Keychain, or ~/.claude/.credentials.json on Linux), extracted to a private temp file and mounted read-write so the in-container claude can refresh the short-lived token. A Claude Code Max/Pro subscriber needs no API key; it just reuses the login. Else
  3. an honest error with setup guidance.
• Forwards ~/.gitconfig and ~/.config/gh (read-only) plus GITHUB_TOKEN/GH_TOKEN if set, so commits and PRs work like local.
• Registers the project with the host dashboard, so one host loki dashboard shows all your loki docker and local loki start projects in a single unified view (see "Run loki in multiple repos" below). Builds run with the dashboard off by default; add --api to publish port 57374 for a single run.

Flags:

The credentials temp file used for Auth method 2 is created with 0600 permissions and wiped on exit. It is never written into the project, never committed, never logged.

Requirements: loki installed on the host (npm/brew/bun) plus Docker. loki docker is a host wrapper; it does not bundle the image, it pulls/runs the published one.

⁠Run loki in multiple repos (unified dashboard)

loki docker is a first-class multi-repo surface, just like the host CLI. You can run loki docker start in several different folders at once:

cd ~/work/api      && loki docker start prd.md
cd ~/work/frontend && loki docker start prd.md
cd ~/work/cli      && loki docker start prd.md

Each repo gets its own container (deterministic name loki-<hash-of-path>), its own bind-mounted /workspace, and its own .loki/ state on the host, so two repos run as two concurrent containers without colliding on a shared port.

Every loki docker project registers on the host (with its real folder path) into the same machine-global registry the host dashboard reads. So one host dashboard shows them all:

loki dashboard      # on the host -- lists ALL projects

The host loki dashboard lists every project whether it runs via local loki start or via loki docker start, and derives each project's running state from its bind-mounted .loki/session.json. One dashboard, all repos, same as the local CLI experience.

Note: loki docker builds run with the dashboard off by default (so concurrent runs never fight over port 57374). The unified view is the host loki dashboard. To bring up the dashboard for a single containerized run instead, use loki docker start --api prd.md, which publishes port 57374 for that one container.

Stopping a containerized build: the dashboard Stop button (and loki stop) signals a loki docker project by writing .loki/STOP into the bind-mounted workspace, which the in-container runner honors at the next iteration boundary. So Stop is reliable but not instant for Docker projects: a build can take up to one provider iteration to wind down, versus the immediate signal a host process receives. To stop a container immediately, use docker stop loki-<hash-of-path>.

⁠Quick Start (docker compose)

If you prefer not to install loki on the host, docker compose runs Loki from the image directly. You set credentials once in a .env file and never retype long flags.

# 1. Get the repo (provides docker-compose.yml and .env.example)
git clone https://github.com/asklokesh/loki-mode.git
cd loki-mode

# 2. Copy the env template and set your key
cp .env.example .env
# edit .env, set ANTHROPIC_API_KEY=sk-ant-...

# 3. Run a build against a spec in the current directory
docker compose run loki start prd.md

To change anything (budget, provider, max iterations), edit .env and run the command again. No flags to retype.

With the dashboard UI:

docker compose run --service-ports loki start --api prd.md
# Dashboard at http://localhost:57374

⁠Quick Start (docker run)

If you prefer docker run, pass the key as an environment variable:

# Pull the latest image
docker pull asklokesh/loki-mode:latest

# Show help
docker run --rm asklokesh/loki-mode

# Start autonomous mode with a spec
docker run -it \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v "$(pwd)":/workspace \
  asklokesh/loki-mode start prd.md

# With dashboard UI
docker run -it \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -p 57374:57374 \
  -v "$(pwd)":/workspace \
  asklokesh/loki-mode start --api prd.md
# Dashboard at http://localhost:57374

⁠Authentication

Loki uses Claude (the only provider pre-installed in the image). There are two ways to authenticate.

⁠Method 1: API key (default, recommended)

Set ANTHROPIC_API_KEY. Get a key from https://console.anthropic.com/settings/keys⁠.

With compose, put it in .env:

# .env
ANTHROPIC_API_KEY=sk-ant-...

With docker run, pass it directly:

docker run -it \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v "$(pwd)":/workspace \
  asklokesh/loki-mode start prd.md

⁠Method 2: Mount host OAuth credentials (Claude Max/Pro subscribers, no API key)

If you have a Claude Code Max or Pro subscription and no API key, mount your host login credentials into the container.

macOS (credentials live in the Keychain, export them to a file first):

security find-generic-password -s "Claude Code-credentials" -w \
  | jq '{claudeAiOauth}' > .loki-oauth-credentials.json

docker run -it \
  -v "$(pwd)/.loki-oauth-credentials.json:/home/loki/.claude/.credentials.json:rw" \
  -v "$(pwd)":/workspace \
  asklokesh/loki-mode start prd.md

Linux (credentials are already a file at ~/.claude/.credentials.json, mount it directly):

docker run -it \
  -v ~/.claude/.credentials.json:/home/loki/.claude/.credentials.json:rw \
  -v "$(pwd)":/workspace \
  asklokesh/loki-mode start prd.md

For compose, uncomment the OAuth-mount volume line in docker-compose.yml.

Notes for Method 2:

• The mount must be rw so refreshed tokens persist back to the host file.
• Never commit .loki-oauth-credentials.json. It contains a live token.
• Tokens are short-lived (hours). If a container sits idle past expiry, re-export the file before the next run.

⁠State and Memory Persistence

Loki writes its state to .loki/ inside /workspace (memory, session, queue, checkpoints). Because the project directory is bind-mounted to /workspace, that state lives on your host and persists across runs. Stop a build and start it again later and it resumes with full memory and session continuity.

⁠Image Details

⁠Usage Examples

# Interactive shell
docker run -it -v "$(pwd)":/workspace asklokesh/loki-mode bash

# Background autonomous mode
docker run -d \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v "$(pwd)":/workspace \
  asklokesh/loki-mode start --bg prd.md

# Quick single-task mode (max 3 iterations)
docker run -it \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v "$(pwd)":/workspace \
  asklokesh/loki-mode quick "add login page"

# Check status
docker run -it -v "$(pwd)":/workspace asklokesh/loki-mode status

# Build a PRD interactively from templates
docker run -it -v "$(pwd)":/workspace asklokesh/loki-mode init

# Generate PRD from a GitHub issue
docker run -it \
  -e GITHUB_TOKEN="$GITHUB_TOKEN" \
  -v "$(pwd)":/workspace \
  asklokesh/loki-mode issue https://github.com/org/repo/issues/42

⁠Providers

Claude is the default provider and the only CLI pre-installed in this image.

To use a Tier 2/3 provider, build a derived image that installs that provider's CLI, then set LOKI_PROVIDER and the relevant API key. Example skeleton:

FROM asklokesh/loki-mode:latest
USER root
# install your provider CLI here (for example, the Codex CLI)
USER loki

docker run -it \
  -e LOKI_PROVIDER=codex \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  -v "$(pwd)":/workspace \
  your-derived-image start prd.md

⁠Volume Mounts

# Full setup with Git and GitHub access
docker run -it \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -e GITHUB_TOKEN="$GITHUB_TOKEN" \
  -v "$(pwd)":/workspace \
  -v ~/.gitconfig:/home/loki/.gitconfig:ro \
  -v ~/.ssh:/home/loki/.ssh:ro \
  -v ~/.config/gh:/home/loki/.config/gh:ro \
  -p 57374:57374 \
  asklokesh/loki-mode start --api prd.md

⁠Environment Variables

⁠Credentials

⁠Core Configuration

⁠Execution Control

⁠Security (Enterprise)

⁠SDLC Phases (all enabled by default, set to false to skip)

LOKI_PHASE_UNIT_TESTS, LOKI_PHASE_API_TESTS, LOKI_PHASE_E2E_TESTS, LOKI_PHASE_SECURITY, LOKI_PHASE_INTEGRATION, LOKI_PHASE_CODE_REVIEW, LOKI_PHASE_WEB_RESEARCH, LOKI_PHASE_PERFORMANCE, LOKI_PHASE_ACCESSIBILITY, LOKI_PHASE_REGRESSION, LOKI_PHASE_UAT

⁠Completion Council

⁠TLS/HTTPS (Dashboard)

⁠CLI Commands

⁠Start Options

--provider NAME     AI provider: claude (default), codex, cline, aider
--parallel          Enable parallel mode with git worktrees
--bg, --background  Run in background
--simple            Force simple complexity tier
--complex           Force complex complexity tier
--github            Enable GitHub issue import
--no-dashboard      Disable web dashboard
--sandbox           Run in Docker sandbox
--skip-memory       Skip loading memory context
--budget USD        Set cost budget limit
--yes, -y           Skip confirmation prompts

⁠Docker Compose Reference

The repo ships a ready-to-use docker-compose.yml with an env_file: .env and an ANTHROPIC_API_KEY passthrough, plus a commented OAuth-mount volume for Auth Method 2. Copy .env.example to .env, set your key, and run. For reference, the service looks like this:

services:
  loki:
    image: asklokesh/loki-mode:latest
    env_file: .env
    volumes:
      - .:/workspace:rw
      - ~/.gitconfig:/home/loki/.gitconfig:ro
      - ~/.ssh:/home/loki/.ssh:ro
      - ~/.config/gh:/home/loki/.config/gh:ro
      # Auth Method 2 (Claude Max/Pro): uncomment to mount host OAuth credentials
      # - ./.loki-oauth-credentials.json:/home/loki/.claude/.credentials.json:rw
    environment:
      - ANTHROPIC_API_KEY
    ports:
      - "57374:57374"
    working_dir: /workspace
    stdin_open: true
    tty: true

cp .env.example .env       # then edit .env and set ANTHROPIC_API_KEY
docker compose run loki start prd.md

⁠Security-Hardened Sandbox

For untrusted PRDs, enterprise, or CI/CD environments:

# Build sandbox image
docker build -t loki-mode:sandbox -f Dockerfile.sandbox .

# Run with resource limits and security controls
docker run -it \
  --cpus=2 --memory=4g --pids-limit=256 \
  --security-opt=no-new-privileges:true \
  --cap-drop=ALL --cap-add=CHOWN \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v "$(pwd)":/workspace \
  loki-mode:sandbox start prd.md

# Or use the built-in sandbox launcher
./autonomy/sandbox.sh start prd.md

Sandbox features: seccomp profile, capability dropping, resource limits, network isolation, optional read-only workspace.

⁠Healthcheck

The image includes a built-in healthcheck that verifies loki version responds correctly. Check container health with:

docker inspect --format='{{.State.Health.Status}}' <container-id>

⁠Tags

⁠Links

• GitHub Repository⁠
• Installation Guide⁠
• Documentation⁠
• PRD Templates⁠

⁠License

Business Source License 1.1 (BUSL-1.1). Source-available, not open source. See LICENSE⁠ and docs/LICENSE-CHANGE-NOTICE.md⁠. Converts to Apache 2.0 on March 19, 2030.

⁠Support

• GitHub Issues⁠
• Documentation Wiki⁠