Skip to the content.

Setup and Runtime

Default local topology

The inspected docker/docker-compose.yml defines these services:

All ports are published on loopback only. Set CLIKE_PROJECTS_DIR in docker/.env (see docker/.env.example): it is mounted read-only at the same path and exposed as DEV_FOLDER. The stack runs with Podman (podman-compose) or Docker Compose.

Service startup model

Gateway

Image command (Python 3.12, dependencies installed from gateway/uv.lock):

uvicorn main:app --host 0.0.0.0 --port 8000

Orchestrator

Image command (Python 3.12, dependencies from orchestrator/uv.lock, plus the eval-toolchain group used by KIT LTC commands while eval runs in this container):

uvicorn app:app --host 0.0.0.0 --port 8080

Both services have compose healthchecks; the orchestrator starts after the gateway is healthy. Both run as the non-root user clike (uid 1000).

Mounts

Eval sandbox

eval-sandbox runs the LTC commands of eval/gate (they are authored by models during /kit). It holds no credentials (it refuses to start if any are present), lives only on the dedicated evalnet network (it cannot reach the gateway or Qdrant), runs non-root on a read-only root filesystem with a 1 GB tmpfs /tmp and its work dirs (venvs, node_modules, npm cache, Playwright browsers) on the eval_work volume (CLIKE_EVAL_BASE_DIR=/var/clike-eval), all capabilities dropped and resource limits, and sees the projects directory read-only. Egress is allowed so that dependency installs work; for offline evaluation (dependencies already available) start the stack with:

podman-compose -f docker-compose.yml -f compose.eval-offline.yml up -d

The sandbox runs with an init (init: true) that reaps the processes the checks orphan.

Eval tools

eval-tools installs the native tools an eval needs (orchestrator/eval_tools_catalog.yaml: database and messaging clients, cloud and IaC CLIs, toolchains β€” conda-forge) into the eval_tools volume, after the developer’s confirmation in VS Code (see auto-eval.md). Only the orchestrator reaches it (toolsnet), it holds no credentials, runs non-root on a read-only root filesystem and installs catalog entries only: conda-forge packages, pip CLIs and download vendor archives (https, verified by sha256). The sandbox mounts the volume read-only and appends /opt/clike-tools/bin to the PATH of the checks. Each tool has its own environment (/opt/clike-tools/envs/<tool>); the exact versions are locked in docker/runs/state/eval-tools/lock.json, from which ./rebuild.sh restores a new volume. ./rebuild.sh --update-tools also updates every tool (and the image’s PostgreSQL client) to its latest version and prints the changes; without it versions do not change. The offline overlay (compose.eval-offline.yml) cuts the sandbox egress only: tools can still be installed.

Gate integrity state (acceptance locks, override audit log) lives in docker/runs/state.

Ollama (optional)

Started only with podman-compose --profile ollama up -d; an init container ensures nomic-embed-text is present.

Qdrant

Runs as the vector store backing RAG persistence.

Main environment variables

Shared (root .env, loaded by both services)

Compose (docker/.env)

Eval / gate (orchestrator)

Orchestrator

Gateway

Important environment variables in compose:

RAG storage, the embedding dimension and the score threshold belong to the orchestrator (EMBEDDING_DIM, RAG_SCORE_THRESHOLD): the gateway is a client of /v1/rag.

Model catalog

The current model catalog is stored in:

It defines:

Default model choices

Current defaults:

Example profile routing

Current examples include:

Current routing map includes:

VS Code extension runtime settings

Current extension settings include:

Core service URLs

Harper and chat

Execution

Eval, gate, finalize

Local agents

Claude Code

GPT Codex

Git

Automation is off by default (see git-and-promotion.md):

Service authentication

MCP (extension operational server)

Security-relevant settings (service URLs, agent binaries/flags/permission and sandbox modes, MCP server, Git remote/push/auto-commit) are machine-scoped: a workspace cannot override them.

Local workspace assumptions

The current source tree assumes:

The extension also expects:

Health endpoints

Useful runtime checks:

Startup guidance

A normal local startup sequence is:

  1. configure .env (provider keys, CLIKE_API_TOKEN) and docker/.env (CLIKE_PROJECTS_DIR)
  2. cd docker && podman-compose up -d --build (Qdrant, gateway, then orchestrator once the gateway is healthy; add --profile ollama for local models)
  3. in VS Code run CLike: Set Service Token
  4. open the CLike chat, fetch models and verify health from the extension
  5. initialize or switch the Harper project if needed

After code changes: cd docker && ./rebuild.sh (cached build, recreated containers, health and image check, eval tools restored from their lock).

Operational cautions