---
title: "Kodema coding agents, LLM proxy and services"
description: "Run coding agents with Kodema: PM/Orchestrator MCP setup, native LLM proxy, budgets, kodema harness exec, OpenCode worktree services and Brain/Hands sandboxes."
canonical_url: https://optimi.com/en/docs/kodema/agents
md_url: https://optimi.com/en/docs/kodema/agents.md
language: en
alternates:
  - lang: fr
    url: https://optimi.com/fr/docs/kodema/agents
    md_url: https://optimi.com/fr/docs/kodema/agents.md
last_updated: 2026-11-22
---

# Coding agents and agentic services

Kodema gives engineering teams a single path from interactive laptop
orchestration to 24/7 autonomous delivery — without exposing raw LLM provider
keys to containers or agent pods, and without writing agent-specific plugins.

## Start here: your harness as PM & Orchestrator

You do not need Kubernetes or local app builds to deliver software with Kodema.
Connect your everyday AI harness (**Claude Code**, **Codex**, **OpenCode** or
**Cursor**) to a local `kodema up` instance:

```sh
kodema up
source ~/.kodema/instances/default/env.sh
printf '%s' "$ANTHROPIC_API_KEY" | kodema secret set ANTHROPIC_API_KEY --stdin
# or OPENAI_API_KEY / OPENCODE_API_KEY, or --value-file <path>
kodema mcp install claude              # or codex, opencode, cursor (--print to preview)
kodema docs install --target agents    # or claude, opencode, all
```

Your harness automatically receives Kodema PM/Orchestrator instructions on MCP
`initialize` plus version-locked `kodema://docs/*` resources and prompts.
Collaborate with it to shape specs in KV (`kv_put`), apply pipelines
(`pipeline_apply`), run multi-stage tasks (`task_create_and_start`,
`task_start`), inspect logs and token usage (`execution_inspect`,
`execution_logs_read`), resolve 3-way reviews (`execution_request_resolve` with
`pass | revise | fail`) and close finished work (`task_complete`) — while all
coding, tests and protected Git merges execute inside Kodema.

## Native LLM proxy and active budgets

Kodema includes a streaming, credential-injecting LLM proxy
(`/llm/{provider}/*`). `kodema up` enables three built-in providers out of the
box, and you can add OpenAI-compatible gateways (OpenRouter, LiteLLM, vLLM,
Ollama) with `--llm-provider` or `--models-file`:

| Provider | Injected container variable | Proxy path | Upstream default | Project secret |
| --- | --- | --- | --- | --- |
| `openai` | `KODEMA_LLM_OPENAI_BASE_URL` | `${KODEMA_URL}/llm/openai/v1` | `https://api.openai.com` | `OPENAI_API_KEY` |
| `anthropic` | `KODEMA_LLM_ANTHROPIC_BASE_URL` | `${KODEMA_URL}/llm/anthropic` | `https://api.anthropic.com` | `ANTHROPIC_API_KEY` |
| `opencode` | `KODEMA_LLM_OPENCODE_BASE_URL` | `${KODEMA_URL}/llm/opencode/v1` | `https://opencode.ai/zen/v1` | `OPENCODE_API_KEY` |
| Custom `<slug>` | `KODEMA_LLM_<SLUG>_BASE_URL` | `${KODEMA_URL}/llm/<slug>/v1` | Configured `base_url` | Configured `secret` |

```sh
kodema up \
  --llm-provider openrouter=https://openrouter.ai/api/v1 \
  --llm-provider local-vllm=http://host.containers.internal:8000/v1,secret=VLLM_API_KEY
```

Provider secrets stay strictly in the control plane: Kodema refuses to mount any
secret owned by a configured LLM proxy provider via container `secrets: [...]`.

### Active token and USD budgets

Active budgets are enforced live before dialing upstream across three scopes:

1. **Per-action:** `budget: {max_tokens, max_cost_usd}` on a container action.
2. **Per-execution:** top-level `budget` on a pipeline (stricter of pipeline and
   installation default wins).
3. **Per-task:** installation default task budget accumulated across sibling
   executions of the same task.

Reaching any limit immediately returns HTTP `429` (`budget_exceeded`) and
records a `model.budget_exceeded` event. Cost budgets fail closed if a model has
no configured pricing rate in `models.json`. Inspect per-execution usage anytime
with `kodema inspect <execution-id>`.

## Pattern A: In-container harnesses (`kodema harness exec`)

Best when each coding or verification stage should run as a stateless container
Job with zero long-lived agent pods.

Wrap any harness command with **`kodema harness exec -- <cmd>`** (compiled into
`/kodema/bin/kodema`, on `PATH` in every container action):

```sh
kodema harness exec -- opencode run "Implement /kodema/task/spec.json and verify tests pass"
kodema harness exec -- claude -p "Implement /kodema/task/spec.json and verify tests pass" --dangerously-skip-permissions
kodema harness exec -- codex exec "Implement /kodema/task/spec.json and verify tests pass"
kodema harness exec -- pi -p "Implement /kodema/task/spec.json and verify tests pass"
```

`kodema harness exec` starts an ephemeral loopback HTTP proxy (`127.0.0.1:0`)
that:

- Trusts `$KODEMA_CA_FILE` on the upstream hop (eliminating `NODE_EXTRA_CA_CERTS`,
  `SSL_CERT_FILE` and `CURL_CA_BUNDLE` boilerplate for LLM traffic).
- Re-reads `/kodema/secrets/KODEMA_TOKEN` fresh on every upstream request, so
  live controller token rotations never trigger `401`.
- Exports `OPENAI_*`, `ANTHROPIC_*`, `OPENCODE_*`, `KODEMA_HARNESS_PROXY_URL`
  and rewritten `KODEMA_LLM_*_BASE_URL` with a random per-invocation local dummy
  API key.
- Auto-populates OpenCode v2 `OPENCODE_CONFIG_CONTENT` when unset or empty,
  routing `opencode` (Zen), `openai` and `anthropic` through the loopback proxy.

### Multi-stage SDLC with 3-way review and Decision IDs

Combine three small pipelines on one task (`completes_task: false`) using the
immutable KV store and `service/merge-coordinator`:

1. **Implement:** reads `spec_key` from KV, runs `kodema harness exec`, pushes
   `refs/heads/work/$KODEMA_TASK`, writes `summary_key` to KV and outputs
   `branch`, `base`, `candidate` and `summary_key`.
2. **Verify and review:** runs deterministic tests in a separate toolchain image
   with `caches: [go-mod, go-build]`, puts the report in KV, and waits at
   `request: role/reviewer`:
   - `kodema approve` (`pass`) mints an immutable `decision_id`.
   - `kodema revise --reason "…"` appends feedback to the task conversation and
     keeps the task `open` without alerting operators.
   - `kodema reject --reason "…"` fails the execution and alerts operators.
3. **Serialized merge:** passes `decision_id` to `request: service/merge-coordinator`
   (`kodema services --kind merge_coordinator`), which serializes pushes to
   `target_ref` and sends `-o kodema.decision_id=<id>` to `kodema git serve`.
   Finish the task explicitly with `kodema task complete <task-id>`.

See the tested YAML suite in
[`examples/agentic-sdlc/`](https://github.com/optimiware/kodema/tree/master/examples/agentic-sdlc).

## Pattern B (Option 1): Per-project OpenCode service (`--mode worktree`)

Graduate to an always-on per-project OpenCode v2 service that maintains durable
`task_id -> opencode_session_id` mappings across `plan`, `implement`, `fix`,
`revise` and `ai_review` turns while isolating each task in its own local Git
worktree (`refs/heads/work/<task-id>`):

```sh
OPENCODE_PASSWORD="$(cat /path/to/opencode.password)" \
  opencode serve --hostname 127.0.0.1 --port 4096

kodema services --kind opencode \
  --mode worktree \
  --service opencode-shop \
  --tenant tenant-local \
  --project project-local \
  --base-url "$KODEMA_URL" \
  --ca-file "$KODEMA_CA_FILE" \
  --credential-file /path/to/opencode-shop.token \
  --state-dir /var/lib/kodema/opencode-shop \
  --git-url "${KODEMA_GIT_URL:-${KODEMA_URL}/git}" \
  --opencode-url http://127.0.0.1:4096 \
  --opencode-password-file /path/to/opencode.password \
  --llm-proxy-listen 127.0.0.1:18080 \
  --per-turn-proxy-routing \
  --max-concurrency 4
```

Key properties:

- **Attributed `kodsvc.` LLM proxy:** Calls `/llm/{provider}/*` using its
  `kodsvc.` token plus `X-Kodema-Execution` and `X-Kodema-Action` headers bound
  to the active `request: service/<id>` action. Kodema enforces execution/task
  budgets, attributes usage to `model_usage` and aborts open streams on
  cancellation or timeout.
- **Minimal role (`roles: []`):** Option 1 worktree mode requires **no
  `engineer` role** — only an enabled project service account plus
  `RW+ refs/heads/work/` in `admin/conf/git.conf`.
- **Live SSE cancellation:** Watches the project event stream and calls OpenCode
  `AbortSession` immediately when an execution is cancelled.
- **Concurrent turns:** Enable `--per-turn-proxy-routing` when running
  `--max-concurrency > 1` behind `--llm-proxy-listen`.

In pipelines, dispatch turns through `request: service/<service-id>` with
`subject.mode` set to `plan`, `implement`, `fix`, `revise` or `ai_review` (plus
`repository`, `base_ref` and optional `plan_key`/`feedback_key`), declaring the
subset of `outputs` you need (`branch`, `candidate`, `summary_key`, `plan_key`,
`review_key`, `session_id`).

## Pattern C (Option 2): Brain/Hands split (`--mode brain` + `kodema sandbox serve`)

Separate LLM reasoning and durable sessions (**Brain**) from build and test
execution (**Hands**) so the Brain pod never executes local shell commands or
touches local source files, and each stage runs on a stock upstream toolchain
image (`golang:1.24`, `node:22`, `python:3.12`):

1. **`kodema sandbox serve` (Hands):** Built into `/kodema/bin/kodema` with pure
   Go stdlib — zero custom agent images needed. Serves Streamable HTTP MCP at
   `POST /mcp` (and `GET /healthz`) jailed strictly to `/workspace` via
   `os.Root`, exposing 6 tools (`read_file`, `write_file`, `edit_file`, `glob`,
   `grep`, `bash`) behind constant-time Bearer auth with token-env stripping and
   process-group timeout teardown.
2. **OpenCode Brain (`--mode brain`):** Disables all built-in local shell and
   filesystem tools in OpenCode and spawns ephemeral per-task sandboxes via
   Kodema’s public API (`KodemaExecutionSandboxManager`):

```sh
kodema services --kind opencode \
  --mode brain \
  --service opencode-shop \
  --tenant tenant-local \
  --project project-local \
  --base-url "$KODEMA_URL" \
  --ca-file "$KODEMA_CA_FILE" \
  --credential-file /path/to/opencode-shop.token \
  --state-dir /var/lib/kodema/opencode-shop \
  --opencode-url http://127.0.0.1:4096 \
  --opencode-password-file /path/to/opencode.password \
  --llm-proxy-listen 127.0.0.1:18080 \
  --max-concurrency 1 \
  --sandbox-default-image docker.io/library/golang:1.24 \
  --sandbox-caches go-mod,go-build \
  --sandbox-port 8090 \
  --sandbox-memory 2Gi \
  --sandbox-cpu 2
```

Important differences from Option 1:

- **Requires `engineer` role:** Brain mode’s service account needs `engineer` to
  spawn inline sandbox executions (`pipeline.start`), tear them down
  (`execution.cancel`) and deliver ephemeral `KODEMA_SBOX_TOK_*` Bearer tokens
  out-of-band (`secret.write` / `secret.delete`).
- **Sandbox-free reasoning turns:** Non-coding turns (`plan`, `ai_review`) that
  omit `sandbox_image` run directly in Brain with no sandbox container.
- **Polyglot toolchains:** Override `sandbox_image`, `sandbox_caches`,
  `sandbox_memory` and `sandbox_cpu` per request action (for example Go for
  backend and Node for frontend in the same pipeline).
- **Concurrency & isolation:** Because OpenCode v2 runtime MCP attachment is
  location-scoped, Brain mode enforces `--max-concurrency 1` per OpenCode v2
  server instance (run separate OpenCode v2 instances for parallel sandboxes).
  On Kubernetes, enable `opencodeBrain` in the `kodema` Helm chart to render
  strict tenant/project NetworkPolicies between Brain pods and
  `kodema.dev/role: sandbox` pods.

## Shared company context and skills

Store team conventions, blueprints and Markdown skills in tenant/project Git
context repositories (`<tenant>/context`, `<tenant>/<project>/context`), then
pull and validate them inside container actions or on workstations:

```sh
kodema context pull --repo context --repo myproject/context \
  --target agents --agents-md AGENTS.md --include-kodema-docs
kodema context list --dir ./context
kodema context show build-and-test --dir ./context
```

`kodema context pull` checks every skill and Markdown file for symlink escapes,
size bounds and credential leaks before materializing them into harness skill
directories (`.agents/skills/`, `.claude/skills/` or `.opencode/skills/`).

Next: **[CLI reference](/en/docs/kodema/cli)** and
**[API and MCP](/en/docs/kodema/api)**.
