loki-mode 11.3.0 → 11.3.1

package/docs/DOCKER.md

@@ -0,0 +1,469 @@
+# 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.
+
+```bash
+# 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:
+
+| Flag | Description |
+|------|-------------|
+| `--image IMG` | Override the image (default `asklokesh/loki-mode:latest`) |
+| `--dry-run` | Print the docker command that would run, then exit |
+
+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:
+
+```bash
+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:
+
+```bash
+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.
+
+```bash
+# 1. Get the repo (provides docker/docker-compose.yml and docker/.env.example)
+git clone https://github.com/asklokesh/loki-mode.git
+cd loki-mode
+
+# 2. Copy the env template and set your key
+cp docker/.env.example .env
+# edit .env, set ANTHROPIC_API_KEY=sk-ant-...
+
+# 3. Run a build against a spec in the current directory
+docker compose -f docker/docker-compose.yml run loki start prd.md
+```
+
+To change anything (budget, provider, max iterations), edit `.env` and run the command again. No flags to retype.
+
+For a mounted config file instead of a long `.env`, pass `loki start --config /path/to/config.yaml` (also accepts `.json`/`.env`; secrets via `${VAR}`). See "Configuration file" in [docs/INSTALLATION.md](INSTALLATION.md).
+
+With the dashboard UI:
+
+```bash
+docker compose -f docker/docker-compose.yml 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:
+
+```bash
+# 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`:
+
+```bash
+# .env
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+With `docker run`, pass it directly:
+
+```bash
+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):
+
+```bash
+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):
+
+```bash
+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/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
+
+| Property | Value |
+|----------|-------|
+| Base | Ubuntu 24.04 |
+| User | `loki` (UID 1000, non-root) |
+| Workdir | `/workspace` |
+| CMD | `loki help` |
+| Exposed Port | `57374` (Dashboard/API) |
+| Node.js | 20 LTS |
+| Python | 3.x (for dashboard server) |
+| GitHub CLI | v2.65.0 |
+| Claude Code CLI | pre-installed |
+
+## Usage Examples
+
+```bash
+# 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.
+
+| Provider | Tier | In this image | Notes |
+|----------|------|---------------|-------|
+| Claude Code | Tier 1 (default) | Yes | Full feature support (subagents, parallel, Task tool, MCP) |
+| OpenAI Codex CLI | Tier 3 | No | Degraded mode (sequential only). Install the CLI in a derived image. |
+| Cline | Tier 2 | No | Reduced parallelism. Install the CLI in a derived image. |
+| Aider | Tier 3 | No | Degraded mode. Install the CLI in a derived 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:
+
+```dockerfile
+FROM asklokesh/loki-mode:latest
+USER root
+# install your provider CLI here (for example, the Codex CLI)
+USER loki
+```
+
+```bash
+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
+
+| Host Path | Container Path | Mode | Purpose |
+|-----------|---------------|------|---------|
+| Project dir | `/workspace` | `rw` | Source code, PRD files, and persisted `.loki/` state |
+| OAuth credentials | `/home/loki/.claude/.credentials.json` | `rw` | Claude Max/Pro login (Auth Method 2) |
+| `~/.gitconfig` | `/home/loki/.gitconfig` | `ro` | Git configuration |
+| `~/.ssh` | `/home/loki/.ssh` | `ro` | Git SSH authentication |
+| `~/.config/gh` | `/home/loki/.config/gh` | `ro` | GitHub CLI authentication |
+
+```bash
+# 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
+```
+
+> **SSH Note**: Prefer SSH agent forwarding over mounting private keys. Mount only `known_hosts` and public keys when possible.
+
+## Environment Variables
+
+### Credentials
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | Anthropic API key (Auth Method 1, default for Claude provider) |
+| `OPENAI_API_KEY` | OpenAI API key (required only for the Codex provider in a derived image) |
+| `GITHUB_TOKEN` | GitHub personal access token |
+
+### Core Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LOKI_PROVIDER` | AI provider: `claude`, `codex`, `cline`, `aider` | `claude` |
+| `LOKI_MAX_ITERATIONS` | Max autonomous iteration cycles | `1000` |
+| `LOKI_MAX_RETRIES` | Max retry attempts per iteration | `50` |
+| `LOKI_DASHBOARD` | Enable dashboard server | `true` |
+| `LOKI_DASHBOARD_PORT` | Dashboard/API port | `57374` |
+| `LOKI_BUDGET_LIMIT` | Max USD spend before auto-pause (e.g. `50.00`) | unset |
+| `LOKI_NOTIFICATIONS` | Desktop notifications | `false` |
+
+### Execution Control
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LOKI_AUTONOMY_MODE` | `perpetual`, `checkpoint`, or `supervised` | `perpetual` |
+| `LOKI_COMPLETION_PROMISE` | Stop condition text (AI outputs this to halt) | unset |
+| `LOKI_PARALLEL_MODE` | Enable git worktree parallelism | `false` |
+| `LOKI_MAX_PARALLEL_AGENTS` | Limit concurrent sub-agents | `10` |
+| `LOKI_SKIP_MEMORY` | Skip loading memory context | `false` |
+| `LOKI_SKIP_PREREQS` | Skip prerequisite checks | `false` |
+
+### Security (Enterprise)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LOKI_STAGED_AUTONOMY` | Require approval before each action | `false` |
+| `LOKI_AUDIT_LOG` | Enable audit logging | `true` |
+| `LOKI_ALLOWED_PATHS` | SANDBOX-SCOPED: host paths the sandbox may mount writable (does NOT restrict agent writes) | all |
+| `LOKI_BLOCKED_COMMANDS` | SANDBOX-SCOPED: blocked `loki sandbox run` argv (does NOT filter agent commands) | `rm -rf /,dd if=,mkfs,...` |
+| `LOKI_SANDBOX_MODE` | Run in Docker-in-Docker sandbox | `false` |
+
+### 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
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LOKI_COUNCIL_ENABLED` | Multi-agent verification council | `true` |
+| `LOKI_COUNCIL_SIZE` | Number of council members | `3` |
+| `LOKI_COUNCIL_THRESHOLD` | Votes required to pass | `2` |
+
+### TLS/HTTPS (Dashboard)
+
+| Variable | Description |
+|----------|-------------|
+| `LOKI_TLS_CERT` | Path to PEM certificate |
+| `LOKI_TLS_KEY` | Path to PEM private key |
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `start [PRD]` | Start autonomous execution |
+| `quick "task"` | Quick single-task mode (max 3 iterations) |
+| `stop` | Stop execution |
+| `pause` / `resume` | Pause/resume execution |
+| `status [--json]` | Show current status |
+| `logs` | Show recent log output |
+| `init` | Build PRD interactively from templates |
+| `issue <url\|num>` | Generate PRD from GitHub issue |
+| `dashboard <cmd>` | Dashboard server: start, stop, status, url, open |
+| `provider <cmd>` | Manage provider: show, set, list, info |
+| `memory <cmd>` | Cross-project learnings |
+| `council <cmd>` | Completion council status |
+| `config <cmd>` | Configuration: show, init, edit, path |
+| `docker <cmd>` | Run any loki command inside the published image (host wrapper, zero config) |
+| `sandbox <cmd>` | Docker sandbox: start, stop, status, logs, shell |
+| `remote [PRD]` | Start remote session (connect from phone/browser, Claude Pro/Max) |
+| `cleanup` | Kill orphaned processes |
+| `version` | Show version |
+| `help` | Show help |
+
+### 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/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:
+
+```yaml
+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
+```
+
+```bash
+cp docker/.env.example .env       # then edit .env and set ANTHROPIC_API_KEY
+docker compose -f docker/docker-compose.yml run loki start prd.md
+```
+
+## Security-Hardened Sandbox
+
+For untrusted PRDs, enterprise, or CI/CD environments:
+
+```bash
+# Build sandbox image
+docker build -t loki-mode:sandbox -f docker/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:
+
+```bash
+docker inspect --format='{{.State.Health.Status}}' <container-id>
+```
+
+## Tags
+
+| Tag | Description |
+|-----|-------------|
+| `latest` | Latest stable release |
+| `8.0.0` | Specific version (current release) |
+| `7.x.x` | Prior versions |
+| `sandbox` | Security-hardened image (Debian slim) |
+
+## Links
+
+- [GitHub Repository](https://github.com/asklokesh/loki-mode)
+- [Installation Guide](https://github.com/asklokesh/loki-mode/blob/main/docs/INSTALLATION.md)
+- [Documentation](https://asklokesh.github.io/loki-mode)
+- [PRD Templates](https://github.com/asklokesh/loki-mode/tree/main/templates)
+
+## License
+
+Business Source License 1.1 (BUSL-1.1). Source-available, not open source. See [LICENSE](https://github.com/asklokesh/loki-mode/blob/main/LICENSE) and [docs/LICENSE-CHANGE-NOTICE.md](https://github.com/asklokesh/loki-mode/blob/main/docs/LICENSE-CHANGE-NOTICE.md). Converts to Apache 2.0 on March 19, 2030.
+
+## Support
+
+- [GitHub Issues](https://github.com/asklokesh/loki-mode/issues)
+- [Documentation Wiki](https://github.com/asklokesh/loki-mode/wiki)