# Home The bridge between AI planners and coding executors. Open-source bridge. Local-first execution. Durable run record across any planner and any executor. Codencer is an open-source orchestration bridge that lets any AI planner — ChatGPT, Claude, Gemini, a human lead — dispatch real work to any AI coding executor — Codex, Claude Code, Antigravity, OpenClaw, Qwen — and produces a durable, auditable record of what happened. We are not a coding agent. We do not run inference. We do not host the LLM. We sit between the planner and the executor as state, contract, and audit trail. Planning stays where it works best. Execution stays near the code. Codencer holds the part that doesn't exist anywhere else: the durable record across a heterogeneous fleet. - Five beta tracks verified: local daemon + CLI · self-host relay + connector · self-host cloud · planner-clients · provider connectors - Executor adapters live: Codex · Claude Code · Antigravity · Qwen — plus OpenClaw experimental - Durable state model: runs · steps · attempts · artifacts · validations · gates — SQLite-backed, worktree-isolated - Cross-platform CI green: macOS · Windows · WSL/Linux at the v0.2.0-beta tag - Documentation discipline: 5,200+ lines across 30+ docs — every claim labeled proven, partial, compatibility-only, or deferred - Hardened by daily use: The founder runs Codencer every day across Mac, Windows, WSL/Linux, and remote VPS # How it works The picture before the prose. Codencer's architecture is three roles, two contracts, one record. # Use cases ## Solo operator A solo dev or a small consultancy juggling multiple AI coding tools across multiple client projects, accountable for code quality and clean handoff. You run Claude Code on one project, Codex on another, Antigravity on a third. Across attempts, you cannot prove what each tool changed, what tests passed, what the diff looked like, what you accepted. When a client asks "show me the trail", you reconstruct from chat logs and git blame. Every attempt becomes a run with structured artifacts. The diff, the test output, the validations — all recorded, all queryable, all replayable. The chat is no longer the source of truth. The run is. # minimal TaskSpec task: name: refactor-payment-handler workspace: ~/projects/clientA executor: codex goal: | Refactor the payment handler to extract retry logic into a separate module. Add tests for the retry path. Keep the existing public API stable. validators: - go test ./... - golangci-lint run make build ./scripts/smoke_test_v1.sh make smoke ## Platform team An engineering lead at a 20–200 engineer company. Your team has shadow AI today — Claude Code, Codex, Copilot, Cursor — installed by individuals, with no shared run truth and no audit posture. You inherit shadow AI. Different teams use different tools. No one can answer "did the AI change this file" with confidence. You cannot prove to security or compliance that AI-driven changes follow your policy. You cannot point an external audit at a single source of truth. Codencer becomes the system of record across whatever AI tools your engineers chose. Each tool's adapter feeds the same state model. The audit log is the same shape regardless of which planner started the run. SSO, SCIM, RBAC are on the roadmap (v0.6, v0.7, v1.0). The local-first execution model means code never leaves your network. # self-host relay topology [ engineer's planner ] ↓ [ your relay ] (runs on your infrastructure, audits everything) ↓ [ each engineer's local connector + daemon ] ↓ [ each engineer's local executor ] PLANNER_TOKEN= make self-host-smoke-mcp ## Regulated industry A platform or security lead in financial services, healthcare, defense-adjacent. Procurement says: code never leaves our network, every change is audited, the vendor cannot retain prompts or outputs. Off-the-shelf AI coding tools fail your procurement review. The vendor has access to source. The vendor retains prompts. The audit trail is a chat transcript, not a structured record. Your security team cannot answer "what did this tool actually do" without the engineer's screenshare. Local-first execution: the code stays on your machines. Self-hosted relay: the audit log stays on your infrastructure. No inference inside Codencer — the bridge does not retain or train on your data, by design. Apache 2.0 license: your legal can read every line. # self-host cloud control plane [ your relay control plane ] (your VPC, your SSO/SCIM) ↓ [ tenant runtime ] (per-team isolation) ↓ [ engineer's local daemon ] (their machine, their network) ↓ [ executor + repo ] # every action emits a structured audit event { "event": "attempt.completed", "run_id": "...", "step_id": "...", "attempt_id": "...", "actor": "alice@acme.com", "executor": "claude-code", "result": "passed", "artifacts": [...], "ts": "2026-04-27T..." } make build-cloud make verify-beta-docker # For teams Make shadow AI auditable. Your engineers are using Claude Code, Codex, Copilot, Cursor, every week. You did not approve a stack. They approved themselves. The risk is not that they're using AI. The risk is that you cannot answer simple questions about what the AI did. Different tools, different teams, no shared run truth. Different audit trails, all of them chat transcripts. No way to answer "did the AI change this file" with a structured record. No way to prove to security or compliance that AI-driven changes follow your policy. No way to point an external audit at a single source of truth. - Durable execution record across the planner-executor-validator loop: Today: runs, steps, attempts, artifacts, validations, gates — across five executor adapters with conformance tests. Tomorrow: validator-as-actor loops and cross-session planner memory on the same substrate. - Planner-neutral: When OpenAI ships hosted Codex agents and Anthropic ships Claude Code Teams, you still want one neutral plane across them. Codencer gets more valuable as vendors collapse, not less. - Local-first execution: The trust model that makes remote planning safe without exposing a raw remote shell. Code never leaves your network. - Open-source-first: Apache 2.0. Your legal can read every line. A moat against lock-in that managed-SaaS competitors structurally cannot match. # About Lukman Nuriakhmetov Founder & CEO · 16 years engineering · 8 years leadership · 6 countries · 7 industries Three years of paying the copy-paste tax — at five companies, leading five teams — codified into infrastructure. Lukman has been a daily user of Claude Code, Codex, Antigravity, and Copilot since 2023. Across cross-border payments at a major financial institution, AI-native infrastructure at Echo Analytics, cloud platforms at Go2Cloud, conversational AI at Zeals, and engineering management at Sberbank, the same gap kept appearing: the planner and the executor were two different tools, and the operator was the bridge. Codencer is the bridge made code. # Sponsor Help us ship the bridge faster. Codencer is open source under Apache 2.0. The OSS Core is free, forever. # Changelog ## v0.2.0-beta v0.2.0-beta ## What's Changed *Finalize v1 cli automation by @lookmanrays in https://github.com/lookmanrays/codencer/pull/1 * feat: implement Codencer v2 local self-host path by @lookmanrays in https://github.com/lookmanrays/codencer/pull/2 ## New Contributors * @lookmanrays made their first contribution in https://github.com/lookmanrays/codencer/pull/1 **Full Changelog**: https://github.com/lookmanrays/codencer/commits/v0.2.0-beta # Roadmap - Apr–May 2026 v0.2.0-beta: Public OSS beta - May 2026 v0.3: Connectors + MCPs - Jun 2026 v0.4: Team self-host - Jul 2026 v0.5: Cloud Preview - Aug 2026 v0.6: Validator loop + audit - Oct 2026 v0.7: Cloud Beta - Jan 2027 v1.0: Cloud GA Public OSS now. Cloud Preview in 3 months. Cloud Beta with paid pilots in 6. Cloud GA in 9. # Docs: Overview What Codencer is and what it isn't. Codencer is the missing operational layer between AI planners and AI coding executors. Planners — ChatGPT, Claude, Gemini, a human lead — decide what to do. Executors — Codex, Claude Code, Antigravity, Qwen, OpenClaw — do it. Codencer sits between them as state, contract, and audit trail. It does not run inference. It does not host the LLM. It does not plan. It records, surfaces, and structures every run, step, attempt, and artifact, across any planner and any executor. ## What Codencer is Codencer is a **planner-to-executor bridge** — a deterministic control plane between LLM-driven planning and local code execution. The planner sends a structured task. Codencer dispatches the work to a coding executor through an adapter. The executor runs locally, in an isolated git worktree, against the operator's repo. Artifacts come back. Validations run. Gates evaluate. The result is a structured record the planner can read and decide on. The planner can be any LLM chat. The executor can be any of the supported adapters. Codencer is neutral on both sides — that's the point. ## What Codencer is not We say no to a long list of things, on purpose: - **Not a coding agent.** Codencer does not write code. The executor does. - **Not a planner.** Codencer does not decide what to do. The planner does. - **Not an LLM host.** Codencer does not call OpenAI, Anthropic, or Google. The planner and executor do, on their own credentials. - **Not a chat UI.** Codencer is a daemon, a CLI, a relay, and a connector. There is no Codencer chat window. - **Not a generic orchestration service.** Codencer is shaped specifically for the planner-executor-validator loop in AI-driven coding work. - **Not a remote shell.** The relay does not expose raw shell, raw filesystem browsing, or arbitrary network tunneling. Operations are bounded by an explicit allowlist. The architectural slogan: *we record, we surface, we structure. We do not train, we do not infer.* ## The three roles Every run involves three actors: - **Planner** — decides what step is next. Holds the high-level plan and the criteria. Outside Codencer's process boundary by design. - **Bridge (Codencer)** — accepts the task, dispatches the step, captures artifacts, runs validations, evaluates gates, returns the structured result. This is what we ship. - **Adapter / executor** — does the actual code change. `codex`, `claude`, `qwen`, `antigravity*`, `openclaw-acpx`. Runs locally on the operator's machine. The contract between planner and bridge is the task spec. The contract between bridge and planner is the result evidence. The contract between bridge and executor is the adapter interface. Three roles, three contracts. ## Why a bridge is the right shape The vendors are deepening their own stacks. ChatGPT now dispatches work to Codex. Claude Desktop now dispatches work to Claude Code. Cursor self-hosted runs Cursor's planner over Cursor's executor. The pattern is the same: vendor-locked planning, vendor-locked execution. Operators who run more than one AI tool — most of the serious ones — are still the bridge. They copy a plan from one chat, paste it into another tool, wait, and copy the result back. They cannot prove what happened across attempts. They cannot replay a successful run. They cannot govern across vendors. A neutral cross-vendor bridge is the gap. Codencer is that bridge. ## Where to start If you want the proof in your terminal: → Read [Quickstart](/docs/quickstart). Local daemon and CLI in under a minute. If you want the model in your head before the prose: → Read [How it works](/how-it-works). Three diagrams and a comparison matrix. If you want the deep technical references — the operator-grade detail this site does not duplicate: → The canonical source is [`github.com/lookmanrays/codencer/tree/main/docs`](https://github.com/lookmanrays/codencer/tree/main/docs). Every claim there is labeled by its current beta truth and known limitation. The site holds the model. The repo holds the truth. # Docs: Quickstart Local daemon + CLI in under 60 seconds. Codencer runs locally. A few commands get you to a green proof on Linux, WSL2, or macOS. The path that follows assumes Go, git, and a working `make` on your PATH. If you don't have them, install them first — Codencer is a Go binary with a CGO SQLite driver and no other runtime dependencies. ## Prerequisites - **Go 1.25.0+** — the daemon, CLI, connector, relay, MCP SDK proof helper, and cloud control plane are all Go binaries. - **Git** — required for worktree isolation; every attempt runs in its own worktree off your repo. - **A C compiler** (`gcc` or `cc`) — required for the CGO-based SQLite driver. - **`curl`** — for health checking and polling helpers. - **`jq` or Python 3** — recommended for shell automation wrappers that parse Codencer's JSON output. Operating systems: Linux native, WSL2 (Ubuntu/Debian), and macOS are supported. Native Windows is not a supported daemon platform — use the Antigravity Broker (`agent-broker`) for cross-side communication; see the [Self-hosting](/docs/self-hosting) chapter. ## Clone and build ```bash git clone https://github.com/lookmanrays/codencer cd codencer make setup # initialize environment, check requirements make build-supported # build the supported beta-track binaries ``` If you only need the local and relay tracks, `make build` is sufficient. If you need the Windows-side broker (Antigravity), add `make build-broker`. Verify the environment: ```bash ./bin/orchestratorctl doctor ``` `doctor` checks every prerequisite and reports green or red on each. If anything is red, fix it before continuing. The runtime-readiness diagnostic is `/api/v1/compatibility` — useful for checking binary availability, simulation mode, and local bindings. ## First proof The simplest proof is the local v1 smoke test. It opens a run, registers a step, dispatches it through the simulation adapter, and verifies the structured result lands. ```bash ./scripts/smoke_test_v1.sh make smoke ``` A few minutes, two commands, green or red. If both are green, your local install is verified at the canonical local proof level. ## What just happened `smoke_test_v1.sh` exercised the daemon in **simulation mode** — no real LLM credits consumed, no real coding agent invoked. It opened a run, registered a single step, and dispatched it through a simulated adapter. The adapter returned a structured artifact. A validation ran. A gate evaluated. The result landed in SQLite. `make smoke` then ran the wider local suite — the canonical local proof per the repo's beta testing guide. ## What's deferred from the canonical local proof > NOTE — `friction`: The canonical local proof is **simulation-first** at the v0.2.0-beta tag. The `codex` adapter has fake-binary `codex exec` coverage and stricter live-smoke checks, but live authenticated Codex service calls remain operator-environment proof. Treat `/api/v1/compatibility` and `orchestratorctl instance --json` as runtime truth for local readiness. For live executor proof beyond simulation, run: ```bash make flagship-planner-smoke # or with a live Codex binary on your PATH: FLAGSHIP_LIVE_CODEX=1 CODEX_BINARY=codex make flagship-planner-smoke ``` ## Next steps The repo's [`BETA_TESTING.md`](https://github.com/lookmanrays/codencer/blob/main/docs/BETA_TESTING.md) is the next page in your sequence. It documents the five public beta tracks: - **Local-only daemon + CLI** — what you just ran. `make smoke`. - **Self-host relay + runtime connector** — `PLANNER_TOKEN= make self-host-smoke-mcp`. See [Self-hosting](/docs/self-hosting). - **Self-host cloud control plane** — `make build-cloud && make cloud-smoke`. Multi-tenant control plane. - **Planner / client integrations** — ChatGPT custom MCP, Claude Code remote MCP, Anthropic Messages API. Operator-loop proof, not universal product compatibility. - **Provider connectors** — Slack strongest, Jira polling-first, others narrower. Each track has its own proof command and its own boundary line in `BETA_TESTING.md`. The boundary line is honest about what's verified and what's compatibility-only. ## When the smoke test fails Three common categories: 1. **Missing prerequisite.** `doctor` will tell you which one. Fix it and re-run. 2. **Stale binary.** Run `make clean && make build-supported`. Rebuild from a clean tree. 3. **Local state drift.** Inspect via `orchestratorctl instance --json` and the daemon's `/api/v1/compatibility` endpoint before resetting anything. If the failure isn't in those three: open an issue with the doctor output, the make target you ran, and the last 50 lines of `orchestratord` log. The repo's [`TROUBLESHOOTING.md`](https://github.com/lookmanrays/codencer/blob/main/docs/TROUBLESHOOTING.md) is the deeper reference. # Docs: Architecture Planner → bridge → executor, the run lifecycle. Codencer's architecture is three roles, two contracts, one record. The roles are planner, bridge, and executor. The contracts are the planner-side task spec and the planner-side result evidence. The record is the run — a structured, append-only, SQLite-backed history of every step, attempt, artifact, validation, and gate the bridge executed. ## High-level model ```text Planner / Chat | | Relay HTTP API or Relay MCP v Relay | | Authenticated outbound websocket v Connector | | Narrow allowlisted local API proxy v Local Codencer Daemon | +--> SQLite state and settings +--> Artifact store +--> Workspace / git manager +--> Validation runner +--> Adapter dispatch +--> Gate and recovery services ``` Execution stays local. Planning stays outside Codencer. Every box above is a real binary in the repo: `orchestratord` (daemon), `codencer-connectord` (connector), `codencer-relayd` (relay), `orchestratorctl` (CLI), with `codencer-cloudd`, `codencer-cloudworkerd`, and `codencer-cloudctl` for the cloud control plane. ## Core runtime roles ### Local daemon (`orchestratord`) The daemon is the local system of record. It owns the state machine. It dispatches adapters. It never accepts inbound traffic from the public internet. Responsibilities: - manage run, step, attempt, and gate lifecycle - persist state to SQLite - dispatch adapters to executors - collect artifacts and validations - expose local `/api/v1` and local compatibility/admin `/mcp/call` The daemon binds to localhost. It is not the public-facing MCP server. > NOTE — `blocker-for-use`: Daemon-local `/mcp/call` is **compatibility-only**. It is not the public remote planner MCP contract. Remote planners belong on relay `/mcp` or cloud `/api/cloud/v1/mcp`. See [`docs/mcp/integrations.md`](https://github.com/lookmanrays/codencer/blob/main/docs/mcp/integrations.md). ### Connector (`codencer-connectord`) The connector is the outbound bridge between relay and local daemon. It opens an authenticated outbound websocket from the operator's network to the relay (no inbound port on the operator's network), then proxies a narrow allowlisted set of operations from relay to daemon. Discovery does not imply exposure — the config file is the allowlist. ### Relay (`codencer-relayd`) The relay is the public planner-facing surface. It speaks HTTP and MCP. It exposes only instance-scoped orchestration operations — open a run, dispatch a step, query a result. It does not expose raw shell, raw filesystem, or arbitrary network tunneling. Authentication is bearer-token; the relay authenticates planners and connectors and routes requests to the right shared local instance. ### Cloud control plane (`codencer-cloudd`, `codencer-cloudworkerd`, `codencer-cloudctl`) For multi-tenant deployments. `cloudd` is the API. `cloudworkerd` runs scheduled work (provider polling, audit aggregation). `cloudctl` is the CLI. Self-host today; managed Cloud Preview launches when the public beta promise extends to it. > NOTE — `blocker-for-use`: Cloud runtime HTTP and cloud MCP are useful only in **composed mode**. A relay connector must be claimed into org/workspace/project scope before cloud can use it. Start `codencer-cloudd` with `--relay-config` or `relay_config_path`, then claim the runtime connector into tenant scope. ## Public surfaces ### Remote / public - relay HTTP API under `/api/v2` - relay MCP under `/mcp` - relay MCP compatibility path `/mcp/call` - connector websocket under `/ws/connectors` ### Local / private by default - daemon HTTP API under `/api/v1` - daemon-local `/mcp/call` (compatibility/admin bridge — not for remote planners) ## State and evidence The current authoritative state lives in the daemon: - runs - steps - attempts - gates - artifacts - validations The relay stores only the remote control-plane state it needs: - connector identity - instance advertisement records - resource routing hints - audit events - enrollment / challenge state ## Trust boundaries - planner decides what to do - relay authenticates and routes - connector limits remote reach to a narrow allowlist - daemon executes and records truth locally - adapters do local work only There is no raw shell or arbitrary filesystem browsing surface in the relay or connector. See [Security & audit](/docs/security) for the deeper trust analysis. ## WSL / Windows model The practical default is: - daemon, connector, repo, worktrees, and artifacts in WSL/Linux - IDE and Antigravity broker on Windows when needed - relay wherever the operator hosts the remote control plane For the deeper architectural detail, see the repo's [`docs/02_architecture.md`](https://github.com/lookmanrays/codencer/blob/main/docs/02_architecture.md). It tracks current implementation status. # Docs: State model Runs, steps, attempts, artifacts, validations, gates. Every Codencer run is a tree. The root is the run itself — one task spec, one or more attempts to satisfy it. Below the run sit steps, the discrete units of work the bridge dispatched. Each step has one or more attempts, because failure is part of the record. Each attempt produces artifacts — files changed, diffs, test output, logs. Validations run against artifacts. Gates evaluate validations. The state model is the thing every other vendor's architecture flattens away. Codencer keeps it, because it's the asset. ## The six entities ### Run The top-level container for a task. One run per submission. Stored in `runs`. A run has a lifecycle status: `pending`, `running`, `completed`, `failed`, `aborted`. Status transitions are deterministic — only the daemon writes them, only through explicit state-machine paths. ### Step A unit of work inside a run. The planner decides which step is next; the bridge executes it. Stored in `steps`. A step has a goal (natural-language), a target executor, and a set of validators and gates. Steps belong to exactly one run. ### Attempt A single execution of a step. Stored in `attempts`. Multiple attempts per step is the norm, not the exception — the executor might fail, the validator might catch a bug, the gate might reject the diff. Each attempt has its own start time, end time, status, and artifact set. Failed attempts are not deleted. They stay in the record as evidence. ### Artifact A file produced by an attempt. Diffs, test output, logs, generated files. Stored in `artifacts` with a path on disk under `artifacts///...`. Artifacts are immutable once written. Re-running an attempt creates new artifacts under a new attempt id; the old ones remain. ### Validation A deterministic check run against the artifacts of an attempt. Validators are shell commands declared as part of the step — `go test ./...`, `pytest`, `pnpm typecheck`, `golangci-lint run`. Stored in `validations` with the command, exit code, stdout/stderr paths, and pass/fail. The validator runner does not interpret the command; it runs it and records the result. ### Gate A policy threshold evaluated against validations and artifacts. Examples: "all validations passed," "diff under 800 lines," "no new dependencies introduced," "no schema migration in the diff." Stored in `gates`. Gates are how the bridge decides whether to surface a step as complete or hold it for human review. ## Append-only design The state tables are append-only. The daemon writes; nothing rewrites. This is deliberate: - A failed attempt stays a failed attempt forever. The audit log shows the failure path, not just the success path. - A successful retry adds a new attempt node; it does not overwrite the previous failure. - A run that gets aborted shows its abort point. No silent rollback. > NOTE — `friction`: Abort remains **best-effort**. Codencer reports a successful abort only when the active step actually reaches `cancelled`. It does not claim universal hard-kill semantics. Inspect step state, result, validations, logs, gates, and artifacts after an abort instead of assuming a forced stop. Append-only is what makes the run record auditable. If the schema permitted updates-in-place, the record would only show the last write — not the history. ## Worktree isolation Each attempt runs in its own git worktree, branched off the operator's repo root. Worktrees are cheap (git is optimized for them) and provide perfect isolation: parallel attempts cannot collide. The flow: 1. Attempt opens. Daemon creates a worktree for the attempt. 2. The executor adapter operates on that worktree, not the operator's working directory. 3. Artifacts are read from the worktree and copied to the attempt's artifact directory. 4. The worktree is closed (kept by default for forensics; configurable retention). The operator's working directory is never touched by an attempt. If three attempts ran in parallel against the same step, each has its own diff, its own test output, its own everything. The state model captures all three independently. ## Cross-session continuity The daemon persists state to SQLite. If the daemon restarts, the state survives. A run that was `running` when the daemon stopped is recovered to its last committed state — pending steps remain pending, in-flight attempts are marked aborted (not lost), and the planner can resume. Cross-session memory at the planner side — the planner remembering what happened across days or weeks of work — is on the post-beta roadmap. The bridge's state model is the substrate for it. ## What's deferred > NOTE — `friction`: A direct public API for listing action-log rows from cloud connectors does not exist yet at the v0.2.0-beta tag. Action-log depth is mainly a store and audit-truth improvement at this point. Use the existing cloud audit and event surfaces for operator visibility until a direct action-log listing route exists. For the schema details and migration history, see the repo's [`docs/02_architecture.md`](https://github.com/lookmanrays/codencer/blob/main/docs/02_architecture.md) and the SQL migrations under [`internal/`](https://github.com/lookmanrays/codencer/tree/main/internal). # Docs: Adapters Codex, Claude Code, Antigravity, Qwen, OpenClaw. An adapter is the contract between Codencer and a coding executor. The adapter knows how to dispatch a step's work to the executor, how to catch the executor's output, and how to surface artifacts back to the run record. Codencer ships several executor adapters in the v0.2.0-beta tag, with conformance tests verifying each one against a known fixture set. ## The adapter contract Every adapter must: 1. **Accept a normalized step input.** Goal, workspace path, validators, environment. The adapter does not see the full task spec — only the per-step slice. 2. **Invoke the executor.** Spawn the executor binary, attach stdio, pass the goal. Each adapter knows its own executor's invocation conventions. 3. **Capture artifacts.** Diff, test output, logs. The adapter copies them to the run's artifact directory. 4. **Return a normalized status.** Completed, failed, aborted. The state machine reads this; nothing else. 5. **Pass conformance tests.** Every adapter has a test suite that runs the same canonical step against a known fixture and verifies the artifacts and status match expectations. The contract is narrow on purpose. Adapters cannot mutate the run record. Adapters cannot bypass validators. Adapters cannot run validations themselves — that is the validation runner's job. ## Local adapter proof levels at v0.2.0-beta | Surface | Current repo proof | Local beta truth | | --- | --- | --- | | Local daemon + CLI + simulation lifecycle | direct smoke + repo tests | canonical | | `codex` adapter | simulation smoke + conformance + fake-binary `codex exec` proof | primary intended local beta adapter; live authenticated Codex service calls remain operator-environment proof | | `claude` adapter | wrapper, prompt, normalize, and fake-binary tests | supported-beta target with narrow wrapper claims only | | `qwen` adapter | conformance / simulation only | secondary | | `antigravity` / `antigravity-broker` | mocked integration and environment-specific proof | secondary | | `openclaw-acpx` | unit and simulation-only proof | experimental / deferred | | `ide-chat` | code/manual handoff only | experimental / deferred | Claude is executed in headless print mode as `claude -p --output-format json`. Codencer writes the built prompt to `prompt.txt`, sends it on `stdin`, and runs the process from the attempt workspace root. ## Adapter conformance tests Each adapter has a conformance test under [`internal/adapter//`](https://github.com/lookmanrays/codencer/tree/main/internal). The tests verify: - The adapter accepts the canonical step input shape - The adapter invokes the executor with the right arguments - The adapter copies artifacts to the expected paths - The adapter returns the expected status for known-good and known-bad fixtures - The adapter does not bypass worktree isolation Conformance tests run in CI on macOS, Windows (where supported), and WSL/Linux. A new adapter cannot land without passing them. ## How to add a new adapter If the executor you want isn't on the list, the path is: 1. Read [`internal/adapter/codex/`](https://github.com/lookmanrays/codencer/tree/main/internal) as the canonical reference. It is the most mature adapter and the cleanest example of the contract. 2. Copy the directory structure to `internal/adapter//`. 3. Implement the four required interface methods: dispatch, capture, status, conformance. 4. Write the conformance test against your executor's known fixtures. 5. Register the adapter in `cmd/orchestratord/main.go` so the daemon dispatches to it when the task spec specifies its name. 6. Run `make build` and the conformance suite. Both green = adapter ships. The adapter API is intentionally simple. Most contributors land their first adapter in a single PR. ## What's deferred > NOTE — `friction`: Adapter-specific features — streaming chain-of-thought, tool-use trace, vendor-specific extensions — are exposed as artifacts where they exist, but Codencer does not normalize them across adapters. The state model captures what every adapter must capture; vendor-specific extras live in the artifact directory and are queryable but not promoted to first-class entities. > NOTE — `experimental`: The `openclaw-acpx` adapter ships at v0.2.0-beta as experimental support via the standardized ACP bridge. Use for evaluation; do not depend on it for production work. For the deep adapter API reference, see the repo's [`docs/06_adapters_and_ide.md`](https://github.com/lookmanrays/codencer/blob/main/docs/06_adapters_and_ide.md). # Docs: Self-hosting Local-only, relay/runtime, cloud control plane. Codencer is local-first by design. The execution layer always runs on the operator's own machine, near the code. The relay layer can run on the operator's infrastructure too. Three deployment modes ship today: local-only, self-host relay, and self-host cloud control plane. ## Local-only The simplest deployment. One machine, one user, one daemon. ```text [ Planner (any chat) ] ── HTTP ──> [ orchestratord (localhost) ] ── adapter ──> [ Local executor ] ── git ──> [ Code ] │ └──> SQLite, artifacts ``` Use this when: - You're a solo operator working on your own machines - You want the lowest-friction path to proof - Your planner is a desktop chat client (ChatGPT, Claude Desktop) or a CLI - You don't need cross-machine access Setup: ```bash git clone https://github.com/lookmanrays/codencer cd codencer make build-supported make smoke ``` Runs in a few minutes. The daemon binds to localhost and is not internet-facing. The repo's [`SETUP.md`](https://github.com/lookmanrays/codencer/blob/main/docs/SETUP.md) is the canonical reference. ## Self-host relay + runtime Adds a relay that the planner talks to over HTTP/MCP. The connector opens an outbound websocket from the operator's network to the relay; the daemon stays local and never accepts inbound traffic. This is the path that makes remote planners work without exposing a raw remote shell. ```text [ Planner ] ── HTTP/MCP ──> [ codencer-relayd ] ↔ [ codencer-connectord ] ── localhost ──> [ orchestratord ] ──> [ Executor ] ↓ ↓ Audit log SQLite ``` Use this when: - You're running a team of operators, each with their own machine - The planner needs to be remote (cloud-hosted ChatGPT, Claude.ai web) - Your security model says no inbound ports to engineer machines - You want a single audit log across the team Setup: ```bash make build PLANNER_TOKEN= make self-host-smoke-mcp ``` The smoke target verifies the full chain: planner → relay → connector → daemon → adapter → result. The repo's [`SELF_HOST_REFERENCE.md`](https://github.com/lookmanrays/codencer/blob/main/docs/SELF_HOST_REFERENCE.md) is the deep reference. ## Self-host cloud control plane Multi-tenant. Adds the cloud control plane (`codencer-cloudd`, `codencer-cloudworkerd`, `codencer-cloudctl`) that bootstraps tenants, provisions runtime workers, and brokers between relay instances and tenant runtimes. ```text [ Planner ] ── ── ── > [ codencer-cloudd ] ── ── > [ Tenant runtime ] ── ── > [ engineer's daemon ] ── > [ Executor ] ↓ Tenant store, audit, quotas ``` Use this when: - You're running across teams or business units inside one org - You need tenant isolation, quotas, and central audit - Your enterprise architecture requires the control plane inside your VPC - You're piloting Codencer with the intent of moving to managed Cloud Preview later Setup: ```bash make build-cloud make cloud-smoke ``` The repo's [`CLOUD_SELF_HOST.md`](https://github.com/lookmanrays/codencer/blob/main/docs/CLOUD_SELF_HOST.md) covers the full bootstrap, tenant provisioning, and the SSO/SCIM-front-door pattern. > NOTE — `blocker-for-use`: Cloud runtime HTTP and cloud MCP are useful only in **composed mode**. A relay connector must be claimed into org/workspace/project scope before cloud can use it. Start `codencer-cloudd` with `--relay-config` or `relay_config_path`, then claim the runtime connector into tenant scope. > NOTE — `friction`: Connector enrollment-token issuance remains **relay-config backed** at v0.2.0-beta. Cloud hosts connector ingress in composed mode, but a cloud-native enrollment-token lifecycle is deferred. Issue enrollment tokens through the relay-backed self-host flow today. ## Docker baseline Every self-host mode has a Docker-baselined verification path: ```bash make verify-beta-docker ``` This builds the supported binaries inside a Docker image and runs the canonical smoke targets inside it. Use this when you want to verify Codencer works on a known-clean image before deploying to your real infrastructure. > NOTE — `friction`: `make cloud-stack-smoke` is the **Docker baseline only**. The Docker compose stack does not create a usable runtime instance by itself, and the broader runtime/MCP/SDK proof lives elsewhere. Use binary-native `make cloud-smoke` with composed-mode inputs when you need claimed runtime visibility, cloud runtime HTTP, cloud MCP, or official Go SDK proof. ## Provider connectors Beyond executor adapters, Codencer ships **provider connectors** — integrations with collaboration tools that planners use as part of their workflow. At v0.2.0-beta: - **Slack** is strongest. The strongest provider-shaped operator path today. - **Jira** is polling-first. Use `codencer-cloudworkerd` for Jira polling. Webhook ingest is explicitly deferred at this tag. - **GitHub, GitLab, Linear** are narrower operator/package surfaces. Use the generic cloud install/action routes and the provider-focused tests in [`docs/CLOUD_CONNECTORS.md`](https://github.com/lookmanrays/codencer/blob/main/docs/CLOUD_CONNECTORS.md). > NOTE — `blocker-for-use`: Jira webhook ingest returns `501 webhook_deferred` at v0.2.0-beta. Do not treat `/webhook` as the supported Jira ingest path. Configure `config.jql` or `config.project_key` with `cloudworkerd` polling instead. ## What "code never leaves the customer's network" means In every self-host mode above, the executor runs locally on the operator's machine. Code never leaves the operator's network. The relay sees task specs and result evidence — structured metadata, not source. The connector proxies a narrow allowlisted API; it does not tunnel arbitrary network traffic. The cloud control plane sees tenant state and audit metadata; it does not see source. This is the trust model that makes Codencer pilotable in regulated industries. See [Security & audit](/docs/security) for the deeper trust analysis. ## What's deferred from the beta promise > NOTE — `friction`: WSL / Windows / agent-broker topology is **operator guidance**, not an automated smoke-proof matrix. Keep the repo checkout, daemon, connector, worktrees, and artifacts in WSL/Linux; keep `agent-broker` on Windows only when needed; inspect results through APIs and CLI rather than raw cross-side paths. > NOTE — `friction`: Managed **Cloud Preview** is on the roadmap. Until then, Codencer is self-host-only. The architecture for the managed Cloud is the same as `cloudd`/`cloudworkerd`/`cloudctl` you can run yourself today; the managed offering adds a hosted relay and tenant provisioning we operate. # Docs: Security & audit Trust model, what's in scope, what's deferred. Codencer's trust model is conservative on purpose. The bridge has authority over the operator's code through a narrow, allowlisted, audited surface. The relay is transport and audit, not a planner. The connector exposes only an allowlisted proxy to the local daemon. No raw remote shell, no arbitrary filesystem surface, no inference run on data the operator hasn't seen. ## Security principles The principles ship as architectural commitments, not aspirations: - **Bridge, not brain.** Codencer executes, waits, records, reports. It does not plan. It does not run inference. - **Local execution.** Adapters and artifacts stay local to the daemon side. The executor's process never sees code from another machine. - **Explicit sharing.** Connector discovery does not imply exposure. The config file is the allowlist. - **Narrow remote surface.** The relay HTTP API and relay MCP expose only instance-scoped orchestration operations. The connector's outbound websocket carries only those operations. - **Evidence first.** Results, validations, and artifacts are recorded as local truth. Nothing the planner says is taken as ground truth without a recorded artifact. ## What the relay can do The relay accepts orchestration operations from authenticated planners: - Open a run against a configured workspace - Dispatch a step to a specific executor - Query run status, step status, attempt status - Retrieve artifacts (over allowlisted paths, bounded transport) - Subscribe to run events for streaming planner UIs That's the whole surface. There is no "execute arbitrary command" verb. There is no "read arbitrary file" verb. There is no "open a network tunnel" verb. ## What the relay cannot do Codencer at v0.2.0-beta does not expose: - Raw shell execution through relay or MCP - Arbitrary filesystem browsing through relay or MCP - Generic network tunneling through the connector - Implicit repo sharing (every workspace must be explicitly configured) - Unauthenticated remote control If something claims to do any of these and calls itself Codencer, it is a fork or a misconfiguration. > NOTE — `friction`: Relay artifact transport is **bounded by design**. The connector is not a bulk file tunnel. Use the normal artifact list and artifact content APIs for bounded evidence retrieval. Keep large-binary transfer expectations out of the relay path. ## What the connector can and cannot do The connector opens a single authenticated outbound websocket from the operator's network to the relay. Through that socket, the relay can invoke the narrow allowlisted operations on the local daemon. The connector cannot: - Open inbound ports on the operator's network - Tunnel arbitrary TCP/UDP traffic - Read files outside the configured workspaces - Bypass the daemon's local API The repo's [`docs/CONNECTOR.md`](https://github.com/lookmanrays/codencer/blob/main/docs/CONNECTOR.md) documents the exact allowlist. ## Local safety Inside the operator's machine, the daemon enforces: - **Repo root anchoring.** Execution is bound to an explicit repo root. Adapters cannot escape it. - **Worktree isolation.** Each attempt runs in its own git worktree. Parallel attempts cannot collide. - **Persisted state.** Run, step, gate, and artifact truth lives in SQLite. Nothing exists only in memory. - **Honest abort semantics.** Codencer reports a successful abort only when the active step actually reaches `cancelled`. ## What gets recorded Every run produces a structured audit trail: - Every state transition (run opened, step dispatched, attempt started, attempt completed, gate evaluated) - Every artifact (diff, test output, log) with content-addressed paths - Every validation (command, exit code, stdout/stderr) - Every gate (rule, evaluation, pass/fail) - The actor that initiated each run (planner identity from the auth token) Append-only. SQLite-backed. Queryable today via the daemon's local `/api/v1` and via SQL against the SQLite file. ## Authentication At v0.2.0-beta: - **Planner tokens.** The planner authenticates to the relay with a long-lived bearer token. Scopes constrain what the token can do. - **Enrollment tokens.** The connector enrolls with the relay using a short-lived token at first connection. After enrollment, the connector authenticates with a per-instance signed challenge/response. - **Local API.** The daemon's local API binds to localhost only. Local processes that share the user account can talk to it. This is intentional — the daemon is the local operator's tool, not a network service. > NOTE — `friction`: Bearer-token mode is the **proven execution credential**. OAuth protected-resource metadata/challenge support exists for product-facing MCP, but Codencer is not an OAuth authorization server and is not enterprise IAM. For ChatGPT/Claude product OAuth flows, front Codencer with an operator-owned issuer or gateway that issues or translates to a bearer token Codencer accepts. See [`docs/mcp/OAUTH_FRONT_DOOR.md`](https://github.com/lookmanrays/codencer/blob/main/docs/mcp/OAUTH_FRONT_DOOR.md). ## What's NOT in scope at v0.2.0-beta The roadmap is concrete on what's deferred. From the canonical [`docs/KNOWN_LIMITATIONS.md`](https://github.com/lookmanrays/codencer/blob/main/docs/KNOWN_LIMITATIONS.md): - **SSO and SCIM** are not in the v0.2.0-beta scope. Use the OAuth front-door pattern with bearer tokens for now. - **RBAC** beyond simple scopes is not in the v0.2.0-beta scope. Today, the planner token's scopes constrain what operations it can perform; richer role-based controls are roadmap. - **A direct public action-log listing API** is not in the v0.2.0-beta scope. Use the existing cloud audit and event surfaces for operator visibility until the listing route exists. - **Generic MCP client universal compatibility** is not claimed. The proven paths are: relay/cloud HTTP, relay/cloud MCP, official Go SDK smoke helper, packaged operator paths for ChatGPT custom MCP, Claude Code remote MCP, and Anthropic Messages API. See [`docs/mcp/integrations.md`](https://github.com/lookmanrays/codencer/blob/main/docs/mcp/integrations.md). - **SLA** and **private deploy** are roadmap items. If your pilot needs one of the deferred features today, we say so. We don't pretend the roadmap is shipped. ## Vulnerability disclosure Security issues should be reported via [GitHub Security Advisories](https://github.com/lookmanrays/codencer/security/advisories) on the repo. For high-severity issues that require coordinated disclosure, email founders@codencer.dev directly. For the deeper operational security reference, see [`docs/07_security_ops.md`](https://github.com/lookmanrays/codencer/blob/main/docs/07_security_ops.md) in the repo. It tracks current implementation status against the principles above.