Setup and Runtime
Default local topology
The inspected docker/docker-compose.yml defines these services:
gatewayon127.0.0.1:8000orchestratoron127.0.0.1:8080qdranton127.0.0.1:6333eval-sandboxβ not published; executes eval/gate commands (see below)eval-toolsβ not published; installs native tools of the eval tools catalog into the volume the sandbox mounts read-onlyollamaon127.0.0.1:11434β optional, only with--profile ollama
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
- orchestrator: the CLike repo read-only at
/workspace(including.git), writable onlysrc/andtests/(generated code),docker/runsat/app/runs, configs read-only, the projects dir read-only at its host path. - gateway:
configsread-only,telemetryread-write,gateway/stubread-only, the projects dir read-only. There is no--reloadin containers: rebuild the images after code changes.
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)
CLIKE_API_TOKENβ required service token (openssl rand -hex 32); every endpoint except/healthrequiresAuthorization: Bearer <token>. Without it the services answer503.CLIKE_ALLOWED_HOSTSβ optional override of acceptedHostnames (defaultlocalhost,127.0.0.1,::1,gateway,orchestrator).- provider keys (
OPENAI_API_KEY,ANTHROPIC_API_KEY, β¦).
Compose (docker/.env)
CLIKE_PROJECTS_DIRβ host folder containing your projects; mounted read-only at the same path and exposed to the services asDEV_FOLDER. Eval/gate only operate on projects under it, or on a project mounted bydocker/mount-project.sh(read-only, that folder only;CLIKE_EVAL_ALLOWED_ROOTSin the git-ignoreddocker/compose.projects.yml). The extension offers it on confirmation.
Eval / gate (orchestrator)
DEV_FOLDERβ allowed root for eval/gate project roots (set fromCLIKE_PROJECTS_DIR).CLIKE_EVAL_SANDBOX_URLβ eval sandbox endpoint (compose:http://eval-sandbox:8090; unset = in-process).CLIKE_EVAL_TOOLS_URLβ eval tools service (compose:http://eval-tools:8091; unset = tools cannot be installed).CLIKE_EVAL_KEEP_REQS(3),CLIKE_EVAL_MIN_FREE_GB(10),CLIKE_EVAL_PROJECT_RETENTION_DAYS(7) β eval disk pruning in the sandbox volume (see auto-eval, Eval disk).CLIKE_DISK_WARN_PERCENT(80) βdocker/rebuild.shwarns when the Podman machine disk is fuller.CLIKE_EVAL_TOOLS_STALE_DAYS(30) β after how many days/toolsandrebuild.shremind you to update the eval tools;CLIKE_EVAL_TOOLS_MAX_DOWNLOAD_MB(1500) β size limit of a vendor archive.CLIKE_STATE_DIRβ gate integrity state (compose:/app/runs/state).CLIKE_EVAL_ALLOWED_ROOTSβ additional allowed roots (path-separator list).CLIKE_ALLOW_INLINE_LTCβ1to accept inline-only LTC profiles (default: the workspace profile file is authoritative).
Orchestrator
CLIKE_CLOUD_MAX_PROMPT_CHARSβ largest cloud prompt CLike sends (default600000chars, about 150k tokens); a larger one is refused with its size (cloud_context_too_large) instead of overflowing the model. Raise it for a model with a larger context.CLIKE_CLOUD_MAX_OUTPUT_CHARSβ largest set of documents a cloud/idea --extendmust write back (default240000chars, about 60k tokens); larger projects run the cascade with a local agent. Important environment variables in compose:GATEWAY_URL=http://gateway:8000RUNS_DIR=/app/runsWORKSPACE_ROOT=/workspace/CODE_ROOT_BASE=srcTEST_ROOT_BASE=testsGENERATED_ROOT=generated(workspace-relative folder for coding-mode files)RAG_BASE_URL=http://localhost:8080/v1/ragRAG_TOP_K=12INLINE_MAX_FILE_KB=64INLINE_MAX_TOTAL_KB=256RAG_SIZE_THRESHOLD_KB=64EMBEDDING_DIM=1536,RAG_EMBED_MODEL=openai:text-embedding-3-small,RAG_SCORE_THRESHOLD=0.30RAG_EMBED_BATCH_SIZE(64),RAG_EMBED_CONCURRENCY(4) β batched, incremental indexingCLIKE_MCP_SERVER_ENABLED=true
Gateway
Important environment variables in compose:
MODELS_CONFIG=/workspace/configs/models.yamlHARPER_TELEMETRY_DIR=/workspace/telemetryCLIKE_TELEMETRY_RETENTION_DAYSβ delete telemetry files (prompts, raw provider responses, rejected artifacts) older than N days; unset or0keeps everything (default).HARPER_STUB_DIR=/workspace/gateway/stubGATEWAY_DUMP_DIR=/app/runs/gateway_dumpsRAG_BASE_URL=http://orchestrator:8080/v1/ragRAG_TOP_K=12RAG_EMBED_MODEL=openai:text-embedding-3-small
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:
configs/models.yaml
It defines:
- defaults
- models
- profiles
- routing
- scoring weights
Default model choices
Current defaults:
chat_model: gpt-5.4-miniembedding_model: openai:text-embedding-3-small
Example profile routing
Current examples include:
plan.fastcode.strictchat.cheaplocal.codegencloud.codegen
Current routing map includes:
idea -> plan.fastspec -> plan.fastplan -> plan.fastkit -> code.strictbuild -> code.strictfinalize -> local.codegenchat -> chat.cheap
VS Code extension runtime settings
Current extension settings include:
Core service URLs
clike.orchestratorUrlclike.gatewayUrl
Harper and chat
clike.harperTimeoutclike.optimizeForclike.chat.persistDirclike.chat.never_send_source_to_cloudclike.chat.autoWriteGeneratedFiles
Execution
clike.execution.defaultPreferenceclike.agentChat.approvals(ask) β approvals of the agent chatβs edits and commands
Eval, gate, finalize
clike.eval.regression(true),clike.gate.strictWarnings(false),clike.gate.autoPromote(merge)clike.autoEval.maxCycles,clike.autoEval.extraCyclesOnProgress,clike.autoEval.afterKit,clike.autoEval.agentEvalChecks(see auto-eval.md)-
clike.evalTools.install(askalwaysnever) clike.kit.acceptanceFirst(false)clike.finalize.verify,clike.finalize.verifyMaxCyclesβ/finalizesolution verification
Local agents
clike.localAgent.enabledclike.localAgent.preferredExecutorclike.localAgent.allowEvalclike.localAgent.restrictToKitPhasesclike.localAgent.timeoutMinutesβ used by executors without their own timeout set (see local-agents.md)
Claude Code
clike.claudeCode.enabledclike.claudeCode.commandclike.claudeCode.modelclike.claudeCode.printModeFlagclike.claudeCode.permissionMode
GPT Codex
clike.localAgent.codex.enabledclike.localAgent.codex.commandclike.localAgent.codex.modelclike.localAgent.codex.sandboxMode
Git
Automation is off by default (see git-and-promotion.md):
clike.git.autoCommit(false) β commit only the files of each phaseclike.git.autoPush(false, machine) β push commits, tags and gate mergesclike.git.gitMergeOnGate(false) β merge the REQ branch after a PASS gateclike.git.openPR(false) β open a PR on/finalizeclike.git.pushRebase(false)clike.git.gitDeleteBranchOnMerge,clike.git.gitReturnToFeatureAfterMergeclike.git.remote,clike.git.remoteUrl,clike.git.defaultBranch,clike.git.branchPrefix,clike.git.tagPrefix,clike.git.conventionalCommits,clike.git.prBodyPath
Service authentication
- the service token is not a setting: run CLike: Set Service Token (stored in SecretStorage)
MCP (extension operational server)
clike.mcp.extensionServerEnabled(false)clike.mcp.extensionServerHost(127.0.0.1),clike.mcp.extensionServerPort(55742)clike.mcp.extensionServerTokenβ optional legacy override; by default a generated token in SecretStorage (CLike: Copy Extension MCP Token)
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:
- repository root mounted read-only under
/workspace(onlysrc/andtests/writable) - run artifacts under
/runs - docs under
docs/harper - source roots normally under
src - test roots normally under
tests
The extension also expects:
.clike/project.jsonfor project metadata where present- session persistence under
.clike/sessionsby default
Health endpoints
Useful runtime checks:
- gateway:
GET /health - orchestrator:
GET /health - orchestrator Harper namespace:
GET /v1/harper/health
Startup guidance
A normal local startup sequence is:
- configure
.env(provider keys,CLIKE_API_TOKEN) anddocker/.env(CLIKE_PROJECTS_DIR) cd docker && podman-compose up -d --build(Qdrant, gateway, then orchestrator once the gateway is healthy; add--profile ollamafor local models)- in VS Code run CLike: Set Service Token
- open the CLike chat, fetch models and verify health from the extension
- 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
- Projects live under
CLIKE_PROJECTS_DIRor are mounted bydocker/mount-project.sh: eval/gate refuse other project roots (403). - Candidate artifacts are stored under
runs/kit/<REQ-ID>/...; do not confuse them with promoted canonical roots. - MCP is optional and mounted only when orchestrator-side enablement is active.