Skip to content
Hub for Orchestrating Managed Execution Runs

Homer Feature Atlas

Start with the seven-step walkthrough; the rest is every capability Homer ships today — command types, inputs, concurrency, human-in-the-loop gates, runners, auth, telemetry, console — each with the shortest thing you can type to use it. Beginner questions are answered at the end.

8 command types 4 execution backends 5 auth schemes 4 SSE streams 98 ADRs
01 — Start here

From nothing to a running agent

Seven steps, about ten minutes. Everything after this section is reference — new to Homer? Read this, then jump to Questions.

Write a config file config.yaml

One file, YAML or JSON, passed as the only argument. Three paths and an auth scheme are all you need to boot. apiAuth is mandatory — running open needs the explicit opt-in below.

server:
  port: 8080
  apiAuth: !<unsecured> {}      # dev only — see step 07

agentsSearchPath: "./agents"
workspaceRootPath: "./workspaces"
databasePath: "./homer.db"

Start the server docker · jar

The compose stack is the fastest path — it brings up the API on :8080 and the console on :3000, pulling the published release images rather than building anything locally. A standalone jar works the same way.

cp .env.example .env
echo "HOMER_ADMIN_TOKEN=$(openssl rand -hex 24)" >> .env
docker compose up -d

# or, without Docker:
java -jar homer-<version>-all.jar config.yaml

Read your first agent example/agents/quickstart/

An agent is a directory under agentsSearchPath holding an agent.yaml — on the compose stack that is example/agents/. Commands run in order. This one, the bundled Quick start agent, uses only !<script> steps, so it needs no LLM: it writes an artifact, asks the operator a question with homer-ask, and gates its last steps on the answer.

example/agents/quickstart/agent.yaml (abridged)
name: quickstart
commands:
  - !<script>
    label: write-report
    content: |
      printf 'Homer quick start ran at %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$HMR_ARTIFACTS_DIR/report.txt"

  - !<script>
    label: ask-ship-it
    timeout: 1800
    content: homer-ask ask-and-wait "Ship it?" --option ship --option hold
    resultEnvParam:
      - { src: STD_OUT, envName: SHIP_ANSWER }

  - !<script>
    label: ship
    when: '[[ "$SHIP_ANSWER" == ship* ]]'
    content: cat "$HMR_ARTIFACTS_DIR/report.txt"

  - !<script>
    label: hold
    when: '[[ "$SHIP_ANSWER" == hold* ]]'
    content: |
      echo "Holding: the operator did not ship it." >&2
      exit 1

  - !<script>
    label: unexpected-answer
    when: '[[ "$SHIP_ANSWER" != ship* && "$SHIP_ANSWER" != hold* ]]'
    content: |
      echo "Unexpected answer: $SHIP_ANSWER" >&2
      exit 1

Run it http

Reload picks up new and changed agents without a restart, and tells you what it found. The run call returns a process id immediately — the work happens in the background, and the run then blocks on its question instead of failing.

# compose stack: add -H "Authorization: Bearer $HOMER_ADMIN_TOKEN" to every call
curl -X POST "http://localhost:8080/api/v1/agents/reload"
curl -X POST "http://localhost:8080/api/v1/agent/quickstart"
# {"processId": 1}

Answer the question, watch it finish console · http

The process page tails the run's logs live; the Questions inbox holds what it is waiting for. Answer ship and the run resumes, prints the artifact it wrote and reaches FINISHED. Answer hold and that step exits non-zero, so the run ends FAILED — the outcome follows your answer, and an answer matching neither option fails the run rather than passing silently.

# console: http://localhost:3000/processes/1
#          http://localhost:3000/questions
# compose stack: sign in first at http://localhost:3000/login?mode=bearer (Token: $HOMER_ADMIN_TOKEN)
curl "http://localhost:8080/api/v1/status/1"
# "status": "FINISHED"
curl "http://localhost:8080/api/v1/artifacts?processId=1&path=report.txt"

Iterate without the server cli

agentdebug validates an agent against the shipped schema and runs it locally — dry-run first to see the exact plan, then a single command at a time.

./app/agentdebug.sh --config config.yaml validate quickstart
./app/agentdebug.sh --config config.yaml run quickstart --dry-run
./app/agentdebug.sh --config config.yaml run quickstart --cmd 0

Turn on auth before anyone else can reach it config.yaml

Give each caller a token with the narrowest grants that work. For the browser console, add a password scheme and pin the console origin — cookie auth needs credentialed CORS.

server:
  apiAuth: !<bearer>
    tokens:
      admin: { token: "@SYSENV:ADMIN_TOKEN", role: admin }
      ci:    { token: "@SYSENV:CI_TOKEN",
               grants: [{ agents: ["hello"], actions: [run, read] }] }
  corsAllowedOrigins: ["http://localhost:3000"]
Next moves. Chain steps with captured output, add an LLM command, gate a run on a human answer, put it on a schedule, or send one heavy step to a build box.
02 — Foundation

The execution model

An agent is a directory with an agent.yaml. Calling it over HTTP returns a process id immediately; the run happens in the background inside its own workspace.

retry (FINISHED/FAILED/KILLED) · resume (LangGraph, FAILED/KILLED/UNKNOWN) — starts a NEW process with the same agent and inputs trigger admission checks CREATED lock WORKING HTTP · cron · dispatch · MCP process row exists WAIT → queue · SKIP_CURRENT → FAILED KILL_OLD_RUN_CURRENT → holder KILLED per command: when? → run → capture env → repeat REJECTED HERE — NO PROCESS IS CREATED authorize → 404 / 403 validate inputs → 400 / 422 cost cap → 429 depth · cycle → 422 cooldown → 429 at capacity → 503 every command ok, or finishExitCode hit non-zero exit · timeout · output cap slot REJECT · queue full · SKIP_CURRENT DELETE /kill · agent reload (queued) or lock collision server restarted mid-run FINISHED FAILED KILLED UNKNOWN ON FINISHED · FAILED · KILLED workdir + .homer deleted (cleanAfterFinish) · continuations fire · open questions expire purgeAfter removes the workspace · record + retained artifacts per retain UNKNOWN (set at startup): questions expire · continuations refire · purgeAfter + retain apply, counted from the restart
What a run passes through. Everything left of CREATED happens before a process record exists — a rejection there leaves nothing to inspect, which is why a failed call and a failed run look so different. All four terminal statuses are final: UNKNOWN is what startup reconciliation writes for a run whose driving coroutine died with the server, and retry or resume never revives a row — it starts a new one.

Agent definitions agent.yaml

Discovery walks agentsSearchPath recursively: any subdirectory holding agent.yaml or agent.json is an agent, up to 8 levels deep (hidden and symlinked directories skipped) — including inside another agent's directory. The search-path root itself is never an agent, and a definition file that is a symlink is not read. agent.yaml is strict (an unknown key is a load error and the agent is skipped); agent.json ignores unknown keys. Names stay one flat namespace and a parent's file API and remote upload cannot reach a nested agent. The file API refuses to write a definition discovery would never load — one deeper than the walk's depth cap, or under a hidden directory — so it cannot leave a subtree it then answers 404 for. The name field must match ^[a-zA-Z0-9_-]+$. An optional group labels the agent for the console: at most 64 characters, non-blank and free of control characters, and returned by GET /api/v1/agents and by every process response (read from the agent's current definition).

agents/hello/agent.yaml
name: hello
description: Greets the caller
group: platform          # optional; the console groups agents by it
commands:
  - !<script>
    content: 'echo "Hello, $NAME!"'

agents/web-pipeline/nodes/analysis/agent.yaml   # a nested agent

Asynchronous invocation http

POST the agent name; you get a process id back at once. Run failures surface by polling status; a request rejected at admission gets an HTTP error and no process.

curl -X POST "$HOMER/api/v1/agent/hello?name=World"
# {"processId": 12345}

Sequential command pipeline agent.yaml

Commands run in declared order in one workspace, each seeing the env the previous ones produced. A failing command stops the run unless it opts out.

commands:
  - !<script> { content: 'git clone "$REPO" .' }
  - !<script> { content: "make build" }
  - !<claude> { prompt: !<prompt> {prompt: "Review it"}, options: {} }

Process lifecycle status

CREATED → WORKING → FINISHED | FAILED | KILLED. A run interrupted by a server restart is reconciled to UNKNOWN (also terminal). A run that fails before any command starts — a claim timeout, a SKIP_CURRENT lock skip, a parallel-run cap, a full queue or an unresolved lockStrategy.key placeholder — carries a stored failureReason saying which.

curl "$HOMER/api/v1/status/12345"

Status history & per-command results status

Every status transition is timestamped, and every command records its kind, start/end, exit code, stdout/stderr paths and an error message — for a skipped command, errMsg carries the skip reason.

.executions[0]
{ "label":"cmd", "kind":"cmd", "resultCode":0,
  "skipped":false, "stdOut":"cmd_0.out" }

Workspace isolation agent.yaml

Each run gets workdir/, artifacts/ and .homer/ under workspaceRootPath. The path template is per agent and is confined to the root.

workspace:
  path: "{{HMR_PROCESS_ID}}"   # or "reports/{{USER_ID}}/{{HMR_PROCESS_ID}}"

Artifacts http

Anything written to $HMR_ARTIFACTS_DIR is downloadable, plus the automatic per-command stdout/stderr pair — cmd_N.out / cmd_N.err unless artifactNameTemplate says otherwise. Listing is capped at 10,000 entries.

curl "$HOMER/api/v1/artifacts/list?processId=12345"
curl "$HOMER/api/v1/artifacts?processId=12345&path=report.md"

Templated artifact names agent.yaml

artifactNameTemplate sets the stem of that automatic pair (Homer appends .out / .err). It is rendered per command and per attempt, so a stem carrying {{HMR_CMD_ATTEMPT}} keeps every retry's output instead of truncating it in place. Secret-classified values are not available to the template, and a rendered name that would still contain one fails the command rather than writing it to a file name.

artifactNameTemplate: "cmd_{{HMR_CMD_INDEX}}_a{{HMR_CMD_ATTEMPT}}"
# default "cmd_{{HMR_CMD_INDEX}}" → cmd_0.out, cmd_0.err, cmd_1.out, …
# omit {{HMR_CMD_INDEX}} and every command shares one pair, each truncating the last

Two-stage cleanup agent.yaml

cleanAfterFinish deletes workdir/ and the .homer/ run tooling the moment the run ends, for at most two minutes — a workspace too large to remove in that budget is left for the second stage; purgeAfter (default 5d — omitting it does not mean "never") later deletes the whole workspace, and the process record with it unless retain holds the record — and any declared artifacts — back. When runs share a fixed path, cleanAfterFinish skips both deletes while another run on that path is still live, so a finishing run cannot strip the helper binaries from a sibling.

workspace:
  cleanAfterFinish: false   # keep the workdir for inspection
  purgeAfter: 7d            # m | h | d | w — default 5d

Records outlive workspaces agent.yaml · server config

retain.recordFor keeps a run's record — status, steps, exit codes, cost — after purgeAfter has removed its directory, so a /processes/{id} link pasted into a ticket keeps resolving. It must be at least purgeAfter, and server.maxProcesses is the hard ceiling above it: at the cap the oldest terminal row is evicted regardless. A record holds the run's input values, so this is also how long a secret input stays in the database. retain.artifacts names globs that ride the same window: matching files stay in place in the artifacts directory, served by the unchanged artifact routes, until the record dies — bounded per run by server.maxRetainedArtifactBytes, with overflow keeping what fits in declared-glob order and flagging retainedTruncated on the status API. It needs a per-run workspace.path containing {{HMR_PROCESS_ID}} (rejected at agent load otherwise).

workspace:
  purgeAfter: 2h
  retain: { recordFor: 30d, artifacts: ["decision.json"] }
server:    { maxProcesses: 10000, maxRetainedArtifactBytes: 16777216 }

Durable state in SQLite config

Processes, questions, dispatches, continuations and the cost ledger live in one SQLite file, so they survive restarts. Put it on a persisted volume in containers.

databasePath: "/var/lib/homer/homer.db"

Retry a finished run http

Replays a FINISHED, FAILED or KILLED process with the same agent and stored inputs (an UNKNOWN run answers 409; resume it if it is a LangGraph run). Inputs are re-validated against the current definition, so tightened rules still apply, and values for inputs removed since are dropped. At process capacity it answers 503.

curl -X POST "$HOMER/api/v1/processes/12345/retry"

Kill a run http

Terminates the process and its whole process group — detached children are reaped too (local via setsid, ssh via a setsid -w wrapper, k8s by deleting the pod, external by a cancel op the instance turns into a group kill).

curl -X DELETE "$HOMER/api/v1/kill/12345"

Graceful stop agent.yaml · k8s runner

Opt in to letting an agent save state when a run is cut short. A step with onTimeout: stop has its own timeout stop the run gracefully instead of failing it, and a Kubernetes runner with gracefulStopSeconds stops the run that many seconds before maxRunSeconds — either way the agent's onStop: steps run once, in order, under the run's remaining deadline, with HMR_STOP_REASON, HMR_STOP_STEP_INDEX, HMR_STOP_STEP_LABEL, HMR_STOP_DEADLINE and (for an interrupted LLM step) HMR_STOP_SESSION_ID telling them what happened. The interrupted step gets interruptGraceSeconds to exit after SIGINT before it is killed, and its spend is still accounted. The run ends FAILED with a stop record naming the reason and how the stop steps went — no separate status.

- !<script>
  label: Run integration tests
  timeout: 3600
  onTimeout: stop          # default: fail
  interruptGraceSeconds: 60 # default 30, 0..600
  content: "pytest -q tests/integration"
onStop:
  - !<script> { label: Save report, content: 'cp report.xml "$HMR_ARTIFACTS_DIR/"' }

Run ownership authz

Every run is stamped with the principal that caused it (ci, hmac:github, session:alice, system:cron) and inherited by sub-runs. Owners can always see and control their own runs.

GET /api/v1/status/12345 → { "owner": "session:alice", … }

Live agent reload http

Rescans the agents directory without a restart and reports what changed. Broken agents are skipped with an error rather than taking the server down. Admin only. Queued runs of an updated or removed agent are killed.

curl -X POST "$HOMER/api/v1/agents/reload"
# {"added":[…], "updated":[…], "removed":[…], "errors":[…]}

Maintenance mode http · operations

An admin holds the server still for a restart: cron fires are skipped, and every other start — HTTP, MCP, a !<agent> hop, a dispatch, a continuation — parks in a bounded queue and starts, in arrival order within one release drain, when the mode goes off (rapid re-toggles overlap drains, so the order across drains is not guaranteed). Runs already WORKING finish untouched, and so do the runs they start: a hop, a dispatch or a continuation fire whose own run is still WORKING is admitted at once instead of parking, so a run that starts another run still finishes through the window — while a start with no parent, or one whose origin has already ended, parks as usual. A schedule missed during the window is not replayed. A start past the queue's size is shed with 429, one past its wait with 503; neither creates a run. The flag survives a restart. The console reads it from GET /api/v1/health and shows a red alert bar across every dashboard page, so a run that seems to do nothing has an explanation on screen.

curl -X POST "$HOMER/api/v1/maintenance" -d '{"enabled": true}'
# {"enabled":true,"since":1761…,"queued":0}   GET reads it back (admin, or read on *)
03 — Command types

Eight ways to do work

Each command is a tagged YAML node (!<cmd>) or a JSON object with a type discriminator. All eight share the same timeout / failure / capture / condition fields (timeout is a no-op on !<agent>, which returns the child's id immediately).

ENV FOR COMMAND N host allowlist (local) globalEnv runner env agent env caller inputs HMR_* injected captured results lower rows win on collision when? template execute on runner exit code exit 0 or continueIfFail capture resultEnvParam {{VAR}} in prompts · LLM options · paths · lock keys false eval error fails = finishExitCode skipped recorded, run continues non-zero exit · timeout · output cap agent FAILED unless continueIfFail FINISHED early remaining commands skipped next command — captured values now outrank every layer below WHILE A COMMAND RUNS stdout / stderr stream to cmd_N.out and cmd_N.err — tailable live over SSE · timeout and output cap polled every 250 ms one telemetry span per command, declared secrets redacted · homer-ask and the MCP question tools reachable from the workspace
What happens to one command, and how the environment grows. The when predicate is part of the command's semantics, not a list-time filter — it gates the step even when you select that step explicitly in a debug run. Note the asymmetry at the exit: continueIfFail moves a non-zero exit onto the capture path, while finishExitCode ends the whole run successfully — and the two interact, since continueIfFail: true disables finishExitCode entirely. A thrown failure — a timeout, an output-cap kill, or any other error — still ends the run even with continueIfFail: true, which only covers a non-zero exit.

!<cmd> — direct exec command

Runs argv straight through ProcessBuilder — no shell, so pipes, globs and $VAR do not expand. Use the list form when arguments contain spaces.

- !<cmd>
  cmd: ["curl", "-H", "Accept: application/json", "https://api.example.com/items"]
  timeout: 30

!<script> — shell script command

A multi-line script piped to <shell> -s - — default sh; any interpreter on the runner's PATH that accepts -s - works, e.g. bash or zsh. This is where pipes, redirection and conditionals belong.

- !<script>
  shell: bash
  content: |
    set -euo pipefail
    jq '.items[].id' data.json > "$HMR_ARTIFACTS_DIR/ids.txt"

!<claude> — Claude Code CLI command

Pipes a prompt into the claude CLI headlessly and captures its NDJSON event stream. Validated fail-closed: needs a result event with subtype: "success" and no is_error. Cost is metered per attempt — one charge, split across its generations when it ends more than one turn — from your spend API when llmPrice.sessionSpend is configured, else from the CLI's own estimate.

- !<claude>
  prompt: !<prompt> { prompt: "Review {{FILE}} for bugs" }
  options: { model: sonnet, allowedTools: [Read, Grep] }
  timeout: 600

!<codex> — OpenAI Codex CLI command

Same shape as the Claude command, driving codex exec --json. Validated fail-closed: needs a turn.completed event and no turn.failed.

- !<codex>
  prompt: !<prompt> { prompt: "Summarize the repo" }
  options: { model: gpt-5.2-codex, sandbox: read-only, cd: repo }

!<opencode> — opencode CLI command

Same shape as the Claude and Codex commands, driving opencode run --format json. Validated fail-closed: needs a step_finish event with a successful finish reason and no failed one.

- !<opencode>
  prompt: !<prompt> { prompt: "Summarize the repo" }
  options: { model: anthropic/claude-sonnet-4-5, agent: build, dir: repo }

!<agent> — run another agent command

Fire-and-forget in-process dispatch of a child agent; the child's process id lands on stdout. Cycle and depth guards apply. The run's owner must be allowed to run the target (or server.agentGrants must delegate the hop); a denied target fails like an unknown one.

- !<agent>
  agentName: deploy-service
  queryParams:
    - { envName: SERVICE, paramName: name, transformer: !<pass> {} }

!<langgraph> — Python graph command

Launches the homer_langgraph runtime, which owns graph execution, durable checkpoints and human-in-the-loop side effects. Requires dispatch.enabled: true.

- !<langgraph>
  module: my_graphs.approval_flow
  python: python3         # interpreter that runs the runtime (default python3)
  inputEnv: GRAPH_INPUT   # non-reserved name to pass fresh input

!<runnerCmd> — one step elsewhere command

Runs a single step on another runner: pre-flight checks, selective upload, execute, selective download. The agent itself must stay on runner: local.

- !<runnerCmd>
  runner: build-box
  check: [which cargo]
  syncToRemote: [src/]
  execute: cargo build --release
  syncFromRemote: [target/release/app]

Timeouts any command

Per-command wall clock in seconds (default 60). On expiry the process group is killed forcibly. Not applicable to !<agent>, whose dispatch returns at once.

- !<cmd> { cmd: "npm ci", timeout: 300 }

Continue on failure any command

continueIfFail: true lets the pipeline proceed past a non-zero exit — for optional cleanup and best-effort steps.

- !<cmd> { cmd: "rm -rf cache", continueIfFail: true }

Early clean exit any command

finishExitCode names an exit code that means "nothing to do": the run finishes successfully and skips the remaining commands.

- !<cmd> { cmd: "./already-deployed.sh", finishExitCode: 127 }

Conditional execution any command

when: takes bash-test expressions, joined by all or any, evaluated against the live env. A false predicate records a skipped execution.

- !<cmd>
  cmd: ./deploy-eu.sh
  when:
    all: ['[ -n "$REGION" ]', '[[ "$REGION" =~ ^eu- ]]']

Custom labels any command

Names the step in the console execution list and in telemetry spans instead of the generic type name.

- !<cmd> { label: "Fetch user data", cmd: "curl https://api.example.com/users" }
04 — LLM commands

Prompts, options, retries

Prompts are inline or pulled from Langfuse by version/label. Option values accept {{VAR}} templating, which is how you reference files shipped beside the agent.

Inline prompt claude · codex · opencode

The prompt text lives in the agent file and is templated against the run env.

prompt: !<prompt>
  prompt: |
    Analyze {{TARGET_FILE}} and list the risky call sites.

Langfuse-managed prompt claude · codex · opencode

Fetches the prompt from Langfuse by name plus an optional version or deployment label — central editing, versioning and A/B testing without redeploying agents.

prompt: !<langfuse>
  promptName: "code-review-prompt"
  label: "production"      # or version: 2

Tool allow/deny lists claude

Scope what Claude may do. allowedTools only pre-approves tools; once permissions are skipped it restricts nothing, so contain a step with disallowedTools or tools — Homer warns at load for a step that sets neither.

options:
  allowedTools: [Read, Grep, Glob]
  disallowedTools: [Bash, Write]

Inline subagents claude

Define named subagents in the agent file; Homer serializes them to the CLI's --agents flag.

options:
  agents:
    code-reviewer:
      prompt: "You review PRs for bugs and style."
      tools: [Read, Grep]
      model: sonnet

Permission mode claude

default, acceptEdits, plan, auto, dontAsk, bypassPermissions. Setting it suppresses --dangerously-skip-permissions.

options: { permissionMode: acceptEdits }

Skip permissions (opt-in) claude

Defaults to false. Turning it on grants unrestricted tool and filesystem access — only for sandboxed environments.

options: { dangerouslySkipPermissions: true }

Budget, turns and effort claude

Bound a single Claude run from inside the agent, independent of the server-side cost caps. Hitting maxTurns fails the step unless maxTurnsExitCode turns it into an ordinary exit code, so a later step (or a parent graph) can decide what to do with the partial work.

options:
  maxTurns: 50
  maxTurnsExitCode: 75   # optional, 1–255; unset = max_turns fails the run
  maxBudgetUsd: 2.5
  effort: high           # low | medium | high | xhigh | max

Escalate to a stronger model claude · codex · opencode

Run a step on a cheaper model first and rerun it on a stronger one only when a when predicate judges the outcome bad. HMR_LLM_OUTCOME tells the predicate how the previous model ended; steps without escalate run once, as before.

options: { model: "{{CHEAP_MODEL}}" }
escalate:
  - model: "claude-opus-5-5[1m]"
    when: '[ "$HMR_LLM_OUTCOME" != success ] || [ ! -f done.txt ]'

Context, system prompts, plugins claude

Add directories, system-prompt files, settings, MCP configs and plugin dirs/URLs — single value or list.

options:
  addDir: ["{{HMR_AGENT_DIR}}/shared", /srv/reference]
  systemPromptFile: "{{HMR_AGENT_DIR}}/system.md"
  mcpConfig: "{{HMR_MCP_CONFIG}}"

Raw CLI escape hatch claude · codex · opencode

Anything the typed options don't cover is appended verbatim. cmd overrides the CLI binary itself (default claude / codex / opencode); it may use {{VAR}}, but an input reference there rejects the agent at load.

options: { options: ["--some-new-flag", "value"] }
cmd: "/opt/claude/bin/claude"   # default: claude / codex / opencode

Retry on transient LLM failure claude · codex · opencode

Retries a non-zero exit or malformed event stream with exponential backoff and full jitter — except a terminal cap stop the command opted into (Claude's maxTurnsExitCode), which is never retried. Other errors (timeouts, cancellation) propagate immediately. Every attempt writes to the same artifact stem unless the agent's artifactNameTemplate carries {{HMR_CMD_ATTEMPT}}, which keeps a failed attempt's output inspectable.

retry: { attempts: 3, baseDelayMs: 2000, maxDelayMs: 20000 }

Codex sandbox & provider overrides codex

Maps 1:1 to codex exec flags, including TOML config overrides for a custom OpenAI-compatible provider.

options:
  sandbox: workspace-write
  config:
    - model_provider=proxy
    - model_providers.proxy.base_url=https://proxy.example.com/v1
    - model_providers.proxy.env_key=PROXY_API_TOKEN

Claude CLI version pin server config

Fails any run whose reported CLI version doesn't match the pin — and does not retry it, since a CLI upgrade can't happen between attempts.

server:
  requireClaudeCodeVersion: "1.0.34"

Dropped Claude telemetry events server config

Drops configured system subtypes from a Claude step's stdout before it is written, so the output cap counts conversation, not telemetry. Third-party models emit one thinking_tokens event per thinking token; the default drops it, and each run's stderr records what was dropped.

server:
  claudeDropSystemSubtypes: ["thinking_tokens"]

Reading LLM output claude · codex · opencode

Each CLI emits one JSON event per line. For jsonPath on stdout Homer re-assembles the stream into a JSON array, so a filter path sees the whole conversation.

resultEnvParam:
  - src: STD_OUT                       # Claude: total spend of the run
    envName: CLAUDE_COST
    transformer: !<regex> { regex: '"total_cost_usd":\s*([0-9.]+)', group: 1 }
  - src: STD_OUT                       # Codex: every agent message, as a JSON array
    envName: CODEX_ANSWER
    transformer: !<jsonPath> { path: "$[?(@.item.type=='agent_message')].item.text" }
05 — Inputs

What callers may send

Each declared input names where it comes from (query, body, header) and which env var it becomes. Validation happens before any process is spawned.

src: query the URL query string src: body the JSON request body src: header matched case-insensitively pass · jsonPath transformer string · integer · number · boolean type values · pattern · min/max length · default constraints into the run env env var 400 — names the param and the rule inputSchema 422 — body violates the schema THE TWO PATHS ARE INDEPENDENT the schema gates the whole payload · inputs extract fields a malformed schema, or a ReDoS-prone pattern, skips the agent at load so does a reserved envName (HMR_* · PATH · LD_* · BASH_ENV …) secret: true changes only what leaves the server, never the value
Both paths run before a process exists, which is why a bad request produces no run to inspect. The split is worth internalizing: inputSchema judges the shape of the whole JSON body and answers 422; the per-input rules judge one value each and answer 400. An agent can use either, both, or neither. The reserved-name guard is not a request stage at all: an input whose envName targets PATH, LD_* or the HMR_* namespace skips the whole agent at load, so no caller can ever reach those names.

Declaring inputs agent.yaml

inputs: is the current field; queryParams: is the legacy alias that still parses.

inputs:
  - paramName: userId
    envName: USER_ID
    src: query
    type: integer
    required: true

Query, body and header sources agent.yaml

Body inputs force POST; a non-empty body needs a JSON content type, while an empty body counts as an empty object for an agent without an inputSchema. Header names are matched case-insensitively and reserved headers are rejected at load.

- { paramName: payload,   src: body,   type: string, envName: PAYLOAD }
- { paramName: X-Trace-Id, src: header, type: string, envName: TRACE_ID }

Typed parameters agent.yaml

string, integer, number, boolean. Legacy uppercase STRING/NUMBER/ANY still work but warn — and ANY validates nothing at all. Omitting type means legacy STRING.

- { paramName: dryRun, type: boolean, default: "false", required: false }

Constraints agent.yaml

Enumerations, regex patterns, numeric bounds, length bounds and defaults — all checked at request time with a message naming the offending rule.

- { paramName: environment, type: string,  values: [dev, staging, prod] }
- { paramName: count,       type: integer, min: 1, max: 100, default: "10", required: false }
- { paramName: ticket,      type: string,  pattern: "^[A-Z]+-[0-9]+$" }

Input transformers agent.yaml

Extract a field out of a structured parameter before it becomes an env var.

- paramName: config
  envName: SERVICE_ID
  transformer: !<jsonPath> { path: "$.service.id" }

Secret inputs agent.yaml

Marks a value for redaction in API responses — process, dispatch and continuation records alike — and in telemetry spans across every command type, and in the LLM event stream (/llm-events) — never in stdout/stderr artifacts or the raw /logs tail, so a command that echoes it stores it in the clear. Declaring it also drops the input's default and values from the GET /api/v1/agents summary and the MCP tool schema, and a value outside a secret's values gets a generic denial that never lists the set. Which values counted as secret is snapshotted when the run starts, so later editing the flag to false cannot reopen records already collected, while setting it now also covers records already retained. A secret value can never reach an artifact file name. It still reaches the run env and the database.

- { paramName: X-Api-Token, src: header, type: string, envName: API_TOKEN, secret: true }

Request-body JSON Schema agent.yaml

inputSchema validates the whole JSON body (Draft 2020-12) and rejects violations with 422 before a process exists. ReDoS-prone patterns are rejected at load.

inputSchema:
  type: object
  required: [service, version]
  properties: { service: {type: string}, replicas: {type: integer, minimum: 1} }
  additionalProperties: false

Reserved env names safety

Inputs and captures can never bind HMR_*, PATH, HOME, BASH_ENV, LD_*, JAVA_*, LC_* and friends — such an agent is skipped at load.

# rejected at load:
- { paramName: p, envName: PATH }
06 — Data flow

Passing values between steps

Command output becomes environment for the next command. Templating and layering rules decide what any given step actually sees.

Capture output to env any command

resultEnvParam pulls from STD_OUT, STD_ERR or RESULT_CODE into a named variable for later steps. One entry per value.

resultEnvParam:
  - { src: STD_OUT, envName: GIT_SHA, transformer: !<pass> {} }
  - { src: RESULT_CODE, envName: EXIT, transformer: !<pass> {} }

JSONPath transformer transformer

Extracts from JSON output — single fields, array elements, wildcards and filters. A selected object or array arrives as compact JSON.

transformer: !<jsonPath>
  path: "$.users[?(@.active == true)].name"

Regex transformer transformer

Pulls a capture group out of free text. Evaluated with a wall-clock bound, so a catastrophic pattern is aborted rather than pinning a CPU. Once one match is shed (by the bound or by pool saturation), later regex transformers of the same list are omitted without being evaluated, as is a pattern that does not compile. In a resultEnvParam, a group beyond the pattern's group count fails the agent, even with continueIfFail.

transformer: !<regex>
  regex: "version: (\\d+\\.\\d+\\.\\d+)"
  group: 1

Pass-through transformer transformer

The default — takes the value as-is.

transformer: !<pass> {}

{{VAR}} templating agent.yaml

Substituted in Claude/Codex/opencode prompts, option values and cmd, !<agent> target names, workspace paths, lock keys and artifactNameTemplate — not in !<cmd> argv or script bodies; a script reads the env as $VAR. An agent whose Claude/Codex/opencode cmd references an input is rejected at load — an input never chooses the executable.

prompt: !<prompt> { prompt: "Review {{FILE}} for bugs" }

Env precedence model

Layered lowest to highest: allowlisted host env (local runs only) → globalEnv → runner env → agent env → caller inputs → injected HMR_* → captured results. A caller can never overwrite a HMR_* value.

parentEnvAllowlist → globalEnv → runner.env → agent.env → inputs → HMR_* → resultEnvParam

Host env is not inherited server config

Only keys on parentEnvAllowlist cross into agent commands. A stray credential exported to Homer's shell never reaches an agent.

parentEnvAllowlist: ["PATH", "HOME", "LANG", "TZ"]

@SYSENV: references config · agent.yaml

Pulls a host env var into config or agent env at load time — so secrets stay out of the files. Missing variables fail fast: a config reference stops startup, and an agent reference skips that agent at load.

globalEnv:
  ANTHROPIC_AUTH_TOKEN: "@SYSENV:ANTHROPIC_AUTH_TOKEN"

Built-in HMR_* variables runtime

Injected into every command (HMR_MCP_CONFIG only with server.mcp.enabled; HMR_PARENT_PROCESS_ID / HMR_ROOT_PROCESS_ID only on runs that have a parent). HMR_AGENT_DIR is also usable in workspace-path and lock-key templates; HMR_AGENT_NAME is not (it is appended after those resolve). Two more — HMR_CMD_INDEX and HMR_CMD_ATTEMPT — are template-only: they exist for artifactNameTemplate rendering and are never exported into a command's environment.

HMR_PROCESS_ID     HMR_WORK_DIR        HMR_ARTIFACTS_DIR   HMR_AGENT_NAME
HMR_AGENT_DIR      HMR_SERVER_ID       HMR_API_URL         HMR_CALLBACK_TOKEN
HMR_MCP_CONFIG     HMR_INVOCATION_CHAIN HMR_PARENT_PROCESS_ID HMR_ROOT_PROCESS_ID
07 — Concurrency

Locks, slots and recursion guards

Two independent limiters — a named lock that serializes runs sharing a key, and a per-agent slot count that bounds parallelism — plus a cooldown that bounds how often an agent may start at all, per agent or per subject it names with cooldown.key.

acceptParentLock — this flow already holds the key concurrent runs of one agent lock key template — global across agents run slot maxParallelRuns — per agent WORKING WAIT → queue behind it SKIP_CURRENT → FAILED KILL_OLD → holder KILLED lock waiters capped by maxQueuedRuns, else by maxParallelRuns the kill waits for the new run's slot REJECT → FAILED at once WAIT → queue maxQueuedRuns bounds that queue — the next run ends FAILED instead of parking TWO SEPARATE GATES slots bound how many run at once locks bound which runs may overlap
Two gates in series, and they answer different questions. A run needs both, so tuning one cannot fix a problem caused by the other — a queue that never drains is usually a lock, not a slot. The order is the lock first, so a run waiting on another run's subject lock holds no slot: one busy subject cannot starve the agent's other subjects, and maxParallelRuns bounds the runs that are actually executing. The scoping differs too: slots are counted per agent, while lock keys are a single global namespace, so two different agents whose key templates resolve to the same string genuinely contend — deliberate, and the mechanism behind serializing a whole RunAgent flow on one key. A key template the run cannot render in full fails it closed: the run ends FAILED with a reason naming the placeholder, before it reaches either gate. cooldown is not one of these gates and is not drawn here: it is a separate bound, refused at the request boundary before either gate, so a start it turns away never queues behind anything.

Lock keys agent.yaml

A templated key decides which runs collide. The default ({{HMR_PROCESS_ID}}) is unique per run, so nothing collides. Keys are global across agents. Every placeholder must have a value: one the run cannot resolve fails the run before it starts rather than being left as literal text, so unrelated runs never share a key by accident.

lockStrategy:
  key: "deploy-{{ENVIRONMENT}}"
  onCollision: WAIT

Collision strategies agent.yaml

Every collision is decided at the lock, before the run holds a slot: WAIT queues behind the holder, SKIP_CURRENT fails the new run (first wins), and KILL_OLD_RUN_CURRENT kills the holder (latest wins) — but only once the new run holds a slot, so a new run refused one leaves the old run alive and releases the lock again.

onCollision: KILL_OLD_RUN_CURRENT   # latest deploy wins

Parent-lock passthrough agent.yaml

Lets a whole RunAgent flow share one key without self-collision: a child whose key matches an ancestor's skips acquisition.

lockStrategy:
  key: "order-{{ORDER_ID}}"
  acceptParentLock: true

Parallel-run cap agent.yaml

Caps the runs of one agent that are executing at once, then either queues or rejects the surplus. A run waiting for its lock holds no slot, so the cap counts running work, not queued work. A rejected run still gets its 200 {processId}; the run itself ends FAILED. The bundled example/agents/limits/ agent is the worked example: one slow script under a cap, a bounded queue and a cooldown.

maxParallelRuns: 5
onMaxParallelRuns: WAIT     # or REJECT (the run ends FAILED at once)

Bounded queue agent.yaml

Under WAIT the queue is unbounded by default; maxQueuedRuns makes the surplus fail fast instead of pinning process rows forever — the call still returns its process id, and the run ends FAILED. It bounds the lock wait too: with it set, lock waiters and slot waiters share the one cap, and without it (or under REJECT) an agent may have at most maxParallelRuns runs waiting for a lock.

maxQueuedRuns: 50

Cooldown between runs agent.yaml

The third bound, and the one about frequency rather than overlap. minInterval spaces out every start; afterFailure backs off only after a run that failed while executing a command — a run refused before it started (a lock skip, a rejected parallel run, a full wait queue, a claim timeout, a full claim queue, an unresolved lock-key placeholder) never arms it — so a fast-failing watcher on a one-minute schedule stops repeating its side effect while a healthy one keeps its cadence. A refused start launches nothing: an HTTP run, retry, resume or debug start returns 429, a cron tick and cron-run only log it, a !<agent> step exits 255, an MCP start returns an error result, a refused continuation fire is retried, and a refused ask-and-dispatch fire ends the dispatch FAILED — the operator's answer is consumed, with no retry. The window is measured from the process table, so it survives a restart. Every start path is covered. Retry, resume and debug still honour minInterval, but ignore afterFailure — unblocking a failed run is the way out of that backoff, not the automated repeat it exists to stop. key counts both windows per rendered subject instead of per agent, so a reviewer started once per merge request is not held back by another request's run; a key that cannot be rendered — an unresolved placeholder, an empty or over-long value — fails the start with 400 rather than sharing one window across every subject.

cooldown:
  minInterval: 5m       # since the previous run started
  afterFailure: 15m     # since the previous FAILED run ended
  key: "mr-{{MR}}"      # …of this merge request, not of the agent

Recursion depth & cycle guard server config

Nested RunAgent hops carry an invocation chain. Exceeding the depth, or revisiting an agent already in the chain, refuses the child run (command exits 255).

server:
  maxAgentInvocationDepth: 5   # A → B → A is refused regardless

Parent/child run linkage API · console

A run started by RunAgent, dispatch, or a continuation records the run that caused it as parentProcessId, and a retry or resume keeps the source run's parent; an external caller links its run with the X-Homer-Parent-Process-Id header (the parent must be visible to it). Each run also carries rootProcessId, the first run of the flow it belongs to, so a whole flow below its root is one paginated read; the run page links to the parent and shows the flow. Inside the run the ids are HMR_PARENT_PROCESS_ID and HMR_ROOT_PROCESS_ID.

GET /api/v1/status/all?parentProcessId=12345   # direct children of one run
GET /api/v1/status/all?rootProcessId=12345     # every run below the flow root
GET /api/v1/status/all?roots=true              # one row per flow
08 — Scheduling

Cron-triggered runs

Any agent can carry a schedule; manual HTTP triggering keeps working alongside it. A schedule tighter than the work it starts wants a cooldown too — a run that fails cheaply holds no lock by the next tick.

Cron schedule agent.yaml

Standard 5-field UNIX syntax with an IANA timezone. A malformed expression is rejected at agent load, not on the first tick.

cron:
  expression: "0 9 * * 1-5"      # weekdays 09:00
  timezone: "Europe/Warsaw"

Schedule status http · console

The agent list reports next run, last run and the last cron-created process id; the console's Schedules page renders them sorted by soonest.

GET /api/v1/agents
"cron": { "nextRunAt": 1700000000, "lastRunProcessId": 42 }

Cron run identity authz

Cron runs get no caller parameters — only the agent's own env plus its inputs' defaults — and are owned by system:cron, so their nested dispatches ride solely on server.agentGrants. An agent whose required input has no default (or an inputSchema required field) can never fire, so its schedule is refused at load: the reason is reported in the reload errors and the agent loads with no active schedule, still runnable by hand. A fire refused by the cost cap, the cooldown, an unresolvable required input or a full process table starts nothing and is only logged (POST /api/v1/agents/{name}/cron-run still answers 204); a SKIP_CURRENT lock collision, a REJECT cap or a full maxQueuedRuns queue creates a run that ends FAILED, as on a tick.

owner: "system:cron"
09 — Human in the loop

Asking the operator

A running command can pause for a human answer. Questions authenticate with a per-process callback token that works only for its own run.

a command asks homer-ask · MCP tool · callback API question OPEN server-side state, not a held socket ANSWERED console, inbox, or the API command resumes answer verbatim on stdout, exit 0 a lapsed wait keeps the id valid — check again, nothing is lost asking process goes terminal, or the server restarts EXPIRED waiters resume with EXPIRED DISPATCH-BOUND exempt from that expiry settled by its dispatch: answer, cancel, or TTL BOUNDS AND CREDENTIALS maxOpenPerProcess · maxConcurrentWaitsPerProcess maxWaitSec clamps one hold, not the question's lifetime authorized by HMR_CALLBACK_TOKEN — this process only
The question outlives the call that asked it, which is the whole design. A timed-out wait is not a failure — the id stays valid and the next check converges on the answer, so a dropped connection or a client that gives up loses nothing. The one thing that does end an open question is its asking process going terminal, and that is exactly the case dispatch-bound questions are exempted from, since their whole purpose is to be answered after the asker is gone.

homer-ask helper shell

Materialized into every workspace at .homer/bin and prepended to PATH when the run's env defines one (otherwise call it by its absolute path). Asks, waits, or polls; the answer arrives on stdout.

ANSWER=$(homer-ask ask-and-wait "Deploy **v2.1** to prod?" \
           --option yes --option no)

Fire-and-forget + poll shell

Waits are resumable — a timeout doesn't lose the question, you check the same id again.

ID=$(homer-ask ask "Which environment?")
homer-ask check "$ID" --wait 55     # exit 3 = still open, ask again

MCP question tools claude

With server.mcp.enabled, Homer pre-generates an MCP config; point the Claude command at it and the model can ask the operator directly.

options:
  mcpConfig: "{{HMR_MCP_CONFIG}}"
  allowedTools: ["mcp__homer-questions__ask_user_and_wait"]
  disallowedTools: ["AskUserQuestion"]

Markdown text & option buttons console

Question text renders as Markdown (HTML escaped, images replaced by their alt text); predefined options become one-click buttons, and free text is always allowed.

homer-ask ask "Pick a region" --option us-east --option eu-west

Answering http · console

Answer from the Questions inbox, the process page, or the API. Answering twice returns 409.

curl -X POST "$HOMER/api/v1/questions/$ID/answer" \
     -d '{"answer":"eu-west"}' -H 'Content-Type: application/json'

Messages to a running run http · console · shell · MCP

The reverse channel: an operator sends a message to a running run and the run decides when to read it. The message waits in the run's inbox as QUEUED and becomes DELIVERED when a step takes it, or UNDELIVERED if the run ends first. Send and list over the API (409 once the run has ended); a shell step reads with homer-inbox, a Claude command through PostToolUse / Stop hooks that call homer-inbox --hook, or the check_messages MCP tool. The run's page in the console shows the messages with their status and, to a user who may control the run, a send box while it is live. A run only ever takes its own messages, and server.messages caps the text length and the messages per run.

curl -X POST "$HOMER/api/v1/status/$PID/messages" \
     -d '{"text":"use the staging db"}' -H 'Content-Type: application/json'
# in the run:
homer-inbox

Question limits server config

Bounds how much a workspace command can pin open: open questions per process, held waits, text length and option count.

server:
  questions: { maxWaitSec: 86400, maxOpenPerProcess: 10,
               maxOptions: 20, maxConcurrentWaitsPerProcess: 32 }
10 — Dispatch & continuations

Starting other agents, and waking up after

Every hop is authorized against the caller's grants or server.agentGrants. Targets of homer-dispatch, ask-and-dispatch and homer-join, and every continuation target (--continue-agent / continueAgent), must additionally opt in with dispatch: { enabled: true }; the in-chain !<agent> command needs no opt-in.

A fired run starts empty: it carries only what the dispatch or continuation passes, not the inputs the registering run resolved. An agent that resumes itself can opt in with continuation: { inheritInputs: true } to keep them, merged under the fire's own params and resume payload — so a resumed segment renders its lock key with the real subject and keeps its tags.fromInputs tags. The fire must target the same agent, the registering run must belong to the same owner, only declared inputs are inherited (reserved HMR_* markers never ride along), and every inherited value is re-validated and its secrets masked exactly as before.

a command !<agent> command same chain — depth and cycle guarded homer-dispatch fresh chain — caller linked as parent ask-and-dispatch the question and the dispatch outlive the caller question OPEN on answer target run own workspace, own callback token, owner inherited dispatch, join and continuation targets set dispatch.enabled — re-checked at fire time …and if it was dispatched with a continuation, its ending wakes something up sub goes terminal package result continuation fires --param went to the sub --continue-param comes here continueAgent runs payload under HMR_LG_RESUME · thread id under HMR_LG_THREAD ≤ 64 KiB → inline result 64 KiB–4 MiB → resultRef fetch with homer-result — reusable within its TTL, bound to the agent no --result-jsonpath, or over 4 MiB: result null, no ref LIFECYCLE PENDING → DISPATCHING → DISPATCHED · FAILED CANCELLED · EXPIRED JOIN — homer-join N subs start at once · ONE continuation fires after the last of them ends results keyed by interrupt id · ≈ slowest sub
Who starts what, and when. The three launch paths differ only in timing and linkage — the run they produce is the same shape either way. The lower band is the piece with no equivalent in an ordinary call: a continuation is registered when the sub starts but fires when it ends, so it routinely outlives both the command that registered it and the run it was watching. That is also why the parameter split matters — --param reaches the sub, --continue-param reaches the follow-up, and a value put on the wrong one is simply lost.

Opting in as a target agent.yaml

Without this flag every dispatch at the agent is refused with 403 — re-checked again at fire time, so disabling it stops pending dispatches too. A hop not authorized to reach the agent gets 404, as if it did not exist.

dispatch:
  enabled: true

Ask and dispatch shell · mcp

Registers a question and a target agent: when the operator answers, that agent starts with the answer as a parameter. Outlives the asking run.

homer-ask ask-and-dispatch "Approve deploy? Which region?" \
  --agent deploy_handler --answer-param region \
  --param service=checkout --option us-east --option eu-west

Grouped ask and dispatch shell · mcp

Registers several questions with one target agent: it starts once, after every question is answered, with the answers in question order. A group holds at most maxGroupSize questions (8 by default).

homer-ask ask-and-dispatch-group \
  --question "Which region?" --option us-east --option eu-west \
  --question "Which service?" \
  --agent deploy_handler --answer-param answers

Immediate dispatch shell

homer-dispatch starts another agent right now, fully decoupled — fresh invocation chain, no question, no blocking. Prints the new process id.

pid=$(homer-dispatch --agent deploy_handler --param region=us-east)

Completion continuations shell

Registers a follow-up agent that fires when the dispatched sub reaches any terminal state, carrying its result. --param goes to the sub, --continue-param to the follow-up. A fire refused for a momentary reason — the target over its cost cap or its cooldown, or a full process table — is retried with backoff rather than dying, bounded by an attempt budget and the continuation's own TTL.

homer-dispatch --agent research_worker --param topic=pricing \
  --continue-agent planner --continue-thread plan-42 \
  --result-jsonpath '$.summary' --ttl 3600

Status hooks agent.yaml

An agent declares which agent to start when a run of its own reaches a status — any of the six, including KILLED and UNKNOWN, so cleanup and restart triage stop needing a command that may never run. Recorded with the status write and fired from every start path (cron, HTTP, MCP, console retry, sub-run), exactly once across a restart, and owned by the triggering run's owner. The target is re-checked at fire time and must not form a cycle; chains are bounded by server.hooks.maxChainDepth.

hooks:
  - FINISHED: collect_artifacts
  - FAILED: notify_oncall
  - KILLED: cleanup_workspace

Parallel fan-out join shell

homer-join starts N subs at once and resumes the parent once, after the last finishes, with every result keyed by interrupt id. Body on stdin. Validation runs before any sub starts; a failure that only surfaces after a start kills the subs this call already started.

homer-join <<'JSON'
{ "subs": [ {"agent":"architect","params":{"topic":"auth"},"interruptId":"a"},
            {"agent":"architect","params":{"topic":"billing"},"interruptId":"b"} ],
  "continueAgent": "graph_runner", "continueThread": "t-1" }
JSON

Large results by reference shell

With --result-jsonpath set, a result over the 64 KiB inline cap (up to 4 MiB of stdout) arrives as a resultRef capability token instead; with no JsonPath, or over 4 MiB, the payload carries result: null and no ref. Fetch the full, server-side transformed value with homer-result. The token is audience-bound: only the continuation's target agent can redeem it, any other gets 403.

homer-result --token "$TOKEN" --out result.txt

Dispatch inbox http · console

List, inspect and cancel pending dispatches and continuations; cancelling a dispatch expires its question so the target never starts. Stored parameter values for the target's secret: true inputs come back as ***. Lists are paginated newest first (limit up to 1000, offset, total), and settled records are deleted after server.dispatch.settledRetentionSec (7 days by default).

curl "$HOMER/api/v1/dispatches?status=PENDING&limit=50"
curl -X DELETE "$HOMER/api/v1/continuations/7"

Dispatch limits server config

maxPending caps pending dispatches and pending continuations, each counted separately; defaultTtlSec and sweepIntervalSec apply to both, joins included. Also the capability-token TTL, maximum join fan-out, the maximum questions one grouped ask-and-dispatch may hold (maxGroupSize) and how long settled records are kept (settledRetentionSec, 7 days by default).

server:
  dispatch: { maxPending: 100, defaultTtlSec: 86400,   # default: none
              resultTokenTtlSec: 3600, maxJoinSubs: 32,
              maxGroupSize: 8,
              settledRetentionSec: 604800 }
11 — LangGraph

Durable Python workflows

The homer_langgraph runtime runs a graph in segments: it executes until the graph completes or parks on an interrupt, performs the implied side effect, and exits. Homer re-enters the thread later.

every segment is a complete Homer run — the thread id is what carries the state across them agent runs from the top langgraph.json thread id, written before graph code runs invoke graph graph completes final state to stdout · exit 0 parks on interrupt one unit resolved per segment DURABLE STATE stateDir / owner / checkpoints.sqlite keyed by thread id · per-owner store is a boundary /processes/{id}/resume re-enters with HMR_LG_RECOVER human gate homer-ask ask-and-dispatch when the operator answers single fan-out homer-dispatch --continue-agent when the sub ends grouped fan-out homer-join — one resume for the group when the LAST sub ends Homer starts the SAME agent again env carries HMR_LG_THREAD · HMR_LG_RESUME · HMR_LG_INTERRUPT the agent re-runs from command 0 — LangGraph replays the parked node up to its interrupt
A workflow is a chain of segments, not one long-running process — which explains the two rules that surprise people. Gates stay pure (homer_interrupt and homer_fanout only call interrupt(); the runtime performs the side effect afterwards) because anything done inside a node fires again on every resume. And since the agent re-runs from its first command, one-shot steps need gating on HMR_LG_THREAD, which is absent only on a fresh run.

Human gate in a graph python

homer_interrupt parks the graph; the runtime asks the operator and resumes the thread with the answer. Gates are pure — the side effect is runtime-owned.

from homer_langgraph import homer_interrupt

def approve(state):
    answer = homer_interrupt("Ship it?", options=["yes", "no"])
    return {"approved": answer == "yes"}

Fan-out to a sub-agent python

Parks the graph, dispatches a Homer agent, and resumes with {status, processId, result}. Large results are fetched by reference automatically; homer_fetch_result redeems a resultRef by hand.

payload = homer_fanout("research_worker", params={"topic": "pricing"},
                       result_jsonpath="$.summary")

Parallel groups python

Two or more fan-outs sharing a group= marker in one segment become a single join: all subs run at once and the graph resumes once. Wall clock ≈ the slowest sub.

homer_fanout("architect", params={"topic": t}, group="designs")

Retry a failed fan-out python

A failed sub arrives as a value, so a plain resume replays it forever. retries= re-dispatches that sub from the original call's args instead, and infra_retries= covers infrastructure outcomes (unknown or unrecognized status, an undecodable payload) on a separate budget — each capped at 5.

payload = homer_fanout("research_worker", params={"topic": topic}, retries=2)
if payload["status"] != "FINISHED":
    ...  # the last attempt's failure, unchanged

Fire-and-forget from a graph python

homer_dispatch shells out immediately and returns a process id — never place it before an interrupt() in the same node, or it fires twice on resume.

pid = homer_dispatch("notifier", {"channel": "#ops"})

Owner-scoped checkpoints server config

Checkpoints live in <stateDir>/<owner>/checkpoints.sqlite, so a forged thread id can only ever reach the forging principal's own state.

server:
  langGraph: { stateDir: /var/lib/homer/langgraph }

Resume a failed run http

Restarts a FAILED/KILLED/UNKNOWN LangGraph run from its latest checkpoint, carrying the original inputs plus recover markers.

curl -X POST "$HOMER/api/v1/processes/12345/resume"

Run introspection http · console

Reports the thread id and, with ?graph=true, the graph topology (nodes and edges) plus per-node status (done/failed/parked/pending/unreached), per-sub progress for fan-out nodes, and traversed: the topology edges the run has actually taken.

curl "$HOMER/api/v1/processes/12345/langgraph?graph=true"

Workflow diagram http · console

Renders each !<langgraph> command's graph natively for the agent detail page, without running anything.

curl "$HOMER/api/v1/agents/approval_flow/langgraph"

Guarding against re-run agent.yaml

Resume re-runs the agent from the top. Gate one-shot steps on the reserved HMR_LG_THREAD marker, which is absent only on a fresh run.

- !<cmd>
  cmd: ./prepare-once.sh
  when: '[ -z "$HMR_LG_THREAD" ]'

Fresh-run input agent.yaml

The default inputEnv is reserved, so a caller can't fill it. Point it at your own input variable to hand the graph a JSON payload.

inputs:  [{ paramName: payload, envName: GRAPH_INPUT, type: string }]
commands: [ !<langgraph> { module: g.flow, inputEnv: GRAPH_INPUT } ]
12 — Runners

Where commands actually execute

An agent picks one backend for all its commands with runner: or runnerTags:; backends are the local host, an SSH host, a Kubernetes cluster, or machines that connect to Homer themselves. Homer stays the source of truth: the workspace syncs out before the run and results sync back after.

Every run waits in one claim queue until a runner with a free permit takes it. An agent picks a runner by alias (runner:) or by tags (runnerTags:); a runner declares the tags it serves and an optional concurrency. One claim TTL (server.runnerClaimTimeoutSec, or the agent's own runnerClaimTimeoutSec) bounds the wait, and the failure names why nobody claimed the run.

HOMER HOST — SOURCE OF TRUTH projectRoot/ workdir/ HMR_WORK_DIR artifacts/ HMR_ARTIFACTS_DIR .homer/bin/ homer-ask, -dispatch .homer/mcp.json HMR_MCP_CONFIG the agent's own directory sits outside it — HMR_AGENT_DIR create · cleanup · purge always run here TARGET — EPHEMERAL COPY /homer/workspace/ k8s emptyDir workdir/ cwd for commands artifacts/ synced back after .homer/bin/ needs sh + curl .homer/agent/ the agent directory (no nested agents) ssh: remoteWorkspaceRoot / the run's relative path every HMR_* path is rewritten to this root HOW CONTENT MOVES local same filesystem — sync is a no-op ssh SFTP, permissions preserved k8s one gzip'd tar per direction, over exec external one gzip'd tar per transfer symlinks escaping the root are skipped !<runnerCmd> does all of this for ONE step, syncing only the paths you name, both ways 01 · open session ssh connects and authenticates · k8s creates the pod local has nothing to open · an external instance claims the run 02 · sync up workspace, then agent dir → .homer/agent minus nested agents, then extraUploads — syncExcludes filter (not on external) 03 · execute env travels per exec, never inside the pod spec · stdout and stderr stream back live into cmd_N.out / .err 04 · sync down artifacts always, as an additive overlay · workdir mirrors only when cleanAfterFinish is false · best-effort, never fatal 05 · sweep ssh removes the root only with cleanAfterFinish, else keeps it · external always removes it · k8s deletes the pod keepPodOnFailure keeps a failed one with a TTL
Synced, not shared. Homer's own copy stays authoritative and the target holds a throwaway duplicate, which is what makes the two asymmetries worth remembering: only artifacts/ comes back unconditionally, and only the paths named in a runnerCmd's syncFromRemote come back at all — so a remote runnerCmd step writing to $HMR_ARTIFACTS_DIR silently loses the output: syncFromRemote paths are workdir-relative, so write results into the workdir and list them there. Sync-down being best-effort is the other one: a failed transfer is logged loudly but leaves an otherwise-successful run marked FINISHED. The tar transfers Homer's own code extracts — k8s sync-down and the external runner's downloads on Homer's side, the external runner's uploads by homer-runner on the instance, both ends sharing one tar implementation — preserve the executable bit, normalized to 0755 or 0644, so a synced script stays callable by name.

Local runner default

Runs on Homer's own host, inheriting the allowlisted host env. server.localRunner holds its claim-queue facets (tags, concurrency) and an enabled switch; enabled: false turns it off, so a run routed to local fails at once and no run executes in the server's container; the server still runs homer_langgraph inspect and state itself, which import the agent's graph module.

runner: local     # implicit default

SSH runner server config

Runs the whole agent on a remote host, syncing over SFTP. Strict host-key checking is on by default and requires a known-hosts file.

runners:
  build-box: !<ssh>
    host: build01.internal
    user: homer
    auth: !<key> { privateKeyPath: /etc/homer/ssh/id_ed25519 }
    knownHostsPath: /etc/homer/ssh/known_hosts
    remoteWorkspaceRoot: /home/homer/homer-workspaces

SSH session timing ssh runner

Idle timeout is disabled by default so a quiet command is never killed by the transport; the command's own timeout is the intended cap. 30 s keepalives are on by default, keeping NAT/proxy idle timers on the path alive and letting the client detect a dead link. Each blocking SFTP round trip (file copy, directory listing, stat, mkdir, and the SFTP client's own close) is additionally bounded by a transfer deadline, so a peer answering keepalives while stalling data cannot hold a run forever. All fields are nullable.

idleTimeoutSeconds: 600       # re-enable; null = disabled (default)
heartbeatIntervalSeconds: 10  # seconds; null = disable keepalives (default 30)
sftpTransferTimeoutSeconds: 60 # per-operation SFTP deadline; null = unbounded (default 300)

Per-runner env ssh · kubernetes · external runners

Remote runners never inherit the backend host's environment — its HOME/PATH are meaningless on another machine (parentEnvAllowlist applies to the local runner only, and a runnerCmd step targeting a remote runner gets the requesting env minus the host layer too). Instead each runner takes its own env, layered between globalEnv and agent env; values support @SYSENV: and join the telemetry redaction set. For a run selected via runnerTags, the serving runner's env is instead merged above agent env once the run is claimed — see the claim queue above. On ssh, sshd and the login shell already supply HOME/PATH — override only what must differ.

runners:
  macos-ios: !<ssh>
    # ...
    env:
      PATH: "/opt/homebrew/bin:/usr/bin:/bin"
      JAVA_HOME: "/Library/Java/JavaVirtualMachines/current"

Kubernetes runner server config

One ephemeral pod per run with a pod-local emptyDir workspace; content moves as gzip'd tar over the exec channel. The image must ship tar and gzip. maxRunSeconds is a hard run limit Kubernetes enforces on the pod, even while Homer is down; opt-in gracefulStopSeconds puts a soft deadline in front of it, interrupting the running step so the agent's onStop: steps can save state before the pod goes; opt-in workload: Job runs the pod in a one-pod Job that waits out namespace quota and is removed by its TTL. A stalled API server fails the run after a fixed 30 s instead of holding it, while the exec and workspace streams stay open. An exec channel that closes while the pod still runs is reported as ExecChannelLost in the run's runner.termination, and the leftover command is killed before the step fails.

runners:
  k8s: !<kubernetes>
    namespace: homer
    image: registry.example.com/homer-runtime:1.22.0
    resources: { limits: { cpu: "2", memory: 2Gi } }
    homerApiUrl: http://homer.homer.svc.cluster.local:8080
    workload: Job        # default Pod
    maxRunSeconds: 7200
    gracefulStopSeconds: 300  # soft deadline 300 s earlier; needs maxRunSeconds

Pod volumes k8s runner

Mount configMaps, secrets, PVCs, hostPaths or emptyDirs — e.g. a persistent build cache alongside the ephemeral workspace.

volumes:
  - { name: gradle, mountPath: /home/homer/.gradle,
      source: !<pvc> { claimName: homer-gradle-cache } }

External runner (pull mode) server config + homer-runner

An !<external> entry is a trust domain: a token and limits. Machines run homer-runner, register with the tags they serve and long-poll Homer for runs, so a box behind NAT works and adding a machine or a tag needs no restart. Every wait is bounded (heartbeat, transfer, per-instance concurrency); a silent instance is dropped and its runs fail. Admins can see every configured runner, its live instances and pending claims via GET /api/v1/runners and GET /api/v1/runners/queue; a principal granted read on * reads the same state with the operator-chosen aliases and instance names withheld. The runner makes its JVM non-dumpable at startup, so a run sharing its user cannot read the domain token out of /proc. An instance that cannot start processes or write its root stops claiming, deregisters and exits 3 for its supervisor to restart. Homer hands each run to the idle instance that claimed least recently.

runners:
  workers: !<external>
    token: "@SYSENV:HOMER_WORKERS_TOKEN"
    allowedTags: [linux, gpu]
# on the machine:
HOMER_RUNNER_TOKEN=… homer-runner --url https://homer.internal --tags linux,gpu --concurrency 2

Runner affinity agent + claim queue

Opt a flow into staying on the instance that served it. An agent declaring runnerAffinity makes the claim queue prefer, for later runs of the same flow, the instance that claimed the flow's earlier ones — so a warmed cache, checkout or model file is not rebuilt on a second machine. It narrows the choice among runners that already match, never widens it; the preference is keyed on the run's own flow root (the first run of the !<agent> chain) and never crosses flows. It is soft: another matching runner passes the run over only until waitSec passes, the run falls back at once when the preferred instance is gone, draining or no longer matching, and an agent without runnerAffinity is never delayed by one with it. An external instance is identified by the name it registered with, and one live instance of a domain holds a name. The memory is in-process and bounded (1024 flows, six hours), so a restart simply loses it.

runnerTags: [linux, gpu]
runnerAffinity: { group: gpu-boxes, waitSec: 30 }

Pod annotations k8s runner

Passed through verbatim — the hook for annotation-driven tooling such as Vault Agent Injector, CSI secret drivers or a service mesh. Prefer file delivery for secrets.

annotations:
  vault.hashicorp.com/agent-inject: "true"
  vault.hashicorp.com/agent-inject-secret-db: secret/data/homer/db

Pod Security Admission support k8s runner

Emit a full pod- and container-level security context so runs work in a restricted namespace. Init containers get the same policy.

securityContext:
  runAsUser: 1000
  runAsNonRoot: true
  allowPrivilegeEscalation: false
  capabilities: { drop: ["ALL"] }
  seccompProfile: { type: RuntimeDefault }

Keep pods for debugging k8s runner

A failed run's pod is kept with a TTL instead of deleted, workspace intact. Operator kills still delete.

keepPodOnFailure: true
keepPodTtlSeconds: 3600

Sync control ssh · k8s · external

syncExcludes trims what gets uploaded: a bare name (e.g. build) matches that entry at any depth, while a leading / anchors the exclude to the upload root (/build skips only the top-level build). extraUploads ships operator-curated host folders into each workspace and repoints an env var at the copy; external domains declare extraUploads too (no syncExcludes there — entries always upload in full).

syncExcludes: [".git", ".gradle", "/build"]
extraUploads:
  - { local: /app/scripts, remote: .homer/scripts, env: SCRIPTS_DIR }

Init containers k8s runner

Run before the workspace is used; the pod is only considered ready once each exits 0.

initContainers:
  - { name: warm-cache, image: busybox:1.36, command: ["sh","-c","..."] }

Orphan pod sweep k8s runner

On boot Homer deletes pods labelled with its own instance id whose process is no longer active, and reports the result on /api/v1/health. No configuration. A workload: Job runner also deletes its orphan Jobs, a Job whose pod was never created included, and skips the pods a Job owns, which go with their Job. Pods and Jobs kept by keepPodOnFailure are skipped. The deleted Jobs are deletedJobs, null when no Job-mode runner was swept.

curl "$HOMER/api/v1/health"   # { "sweep": { "scanned":…, "deleted":…, "deletedJobs": null } }

Callback URL for remote runs ssh · k8s · external

Remote environments need a reachable Homer URL for homer-ask, the MCP question tools and the dispatch / join / result helpers and homer-tag. Without it those fail silently while plain commands succeed. !<agent> (RunAgent) dispatches in-process and needs no URL. An external domain accepts only https:// (or loopback http://), without embedded credentials.

homerApiUrl: http://homer.homer.svc.cluster.local:8080   # ssh / k8s
homerApiUrl: https://homer.internal                      # external

Remote environment contract ssh · k8s · external

Homer installs nothing on the target. The image or host must supply /bin/sh, curl, tar+gzip, and rm (fast cleanAfterFinish teardown on ssh; without it cleanup falls back to a slow per-file SFTP walk), plus claude / codex / opencode / homer_langgraph if those command types are used. An ssh runner's remoteWorkspaceRoot must be an absolute, normalized path other than /; config load rejects anything else. For an external domain the environment is the machine the homer-runner instance runs on: it needs /bin/sh and curl for the helpers, plus claude / codex / opencode / homer_langgraph if used, while tars and teardown are the instance's own work; the reference image ships none of claude, node or python.

# minimum for a k8s runner image
apk add --no-cache tar gzip curl
13 — HTTP API

The full endpoint surface

Everything under /api/v1, plus the MCP endpoints. Health probes and login are unauthenticated; workspace callbacks use the per-process token; the /api/v1/runner/* protocol routes use a runner domain token (runners.*.token) — a principal class of its own, 401 everywhere else, and every apiAuth credential is 401 on those routes; every other route is authorized per request. On the run, debug and LangGraph-inspect routes an agent you hold no grant on returns the same 404 as a missing one; the cron-run route is admin-only and grants play no part on it — a non-admin gets the same 404 as a missing agent (ADR-0080); the agent-file routes answer 403 before any lookup. A process or record you may not see is always 404, and so is a missing control/run action on one you can see (kill, retry, resume, answer, cancel); a missing action on an agent route (run, debug, files) is a 403.

Endpoints

MethodPathWhat it does
GET/api/v1/livezLiveness probe — always 200. Wire livenessProbe here.
GET/api/v1/readyzReadiness probe — 503 once drain begins. Wire readinessProbe and proxy upstream checks here.
GET/api/v1/heartbeatPing with the server version; requires a valid credential under any configured scheme (open only under unsecured), so it doubles as a credential check.
GET/api/v1/healthRich JSON status: runners plus the orphan-pod sweep snapshot; configured runner aliases are admin-only. Not a probe.
GET/api/v1/statusServer status (admin).
GET/api/v1/runnersConfigured runners with permits in use, and each external domain's live instances (admin, or read on * with aliases and instance names withheld).
GET/api/v1/runners/queuePending runner claims: count, oldest age, breakdown by filter (admin, or read on * with alias filters withheld).
GET/POST/api/v1/agent/{name}Run an agent. POST is the supported verb; GET is deprecated.
GET/api/v1/agentsList agents, filtered to those you hold a grant on, with inputs, cron state and writable.
POST/api/v1/agentsCreate a new agent directory.
POST/api/v1/agents/reloadRescan the agents directory (admin).
GET/api/v1/agents/{name}/langgraphGraph topology (nodes and edges) for each LangGraph command.
GET/api/v1/agents/{name}/filesList an agent directory (edit grant).
GET/PUT/DELETE/api/v1/agents/{name}/files/…Read, write and delete files in an agent directory; writes are schema-validated.
POST/api/v1/agents/{name}/debugRun one command of an agent with ad-hoc env and params.
POST/api/v1/agents/{name}/cron-runFire any agent immediately with cron semantics, with or without a cron block — no parameters, owned by the scheduler (admin; a denial is the same 404 as an unknown agent, and a preflight refusal starts nothing and still answers 204).
GET/api/v1/schemas/agentThe agent JSON Schema (used by the console editor).
GET/api/v1/status/{id}One process: history, executions, inputs, cost, cost source, runner state, open questions, Langfuse trace link, parent run id.
GET/api/v1/status/allProcess list with types, agentName, parentProcessId (children of one run), rootProcessId (every run below the flow root; a root the caller cannot see reads as an empty list) and roots=true (one row per flow), tag (repeatable, ANDed subject-tag filter; at most 10, matches bounded at 10 000 rows), order, limit (default 100, max 1000), offset.
DELETE/api/v1/kill/{id}Kill a running process.
POST/api/v1/processes/{id}/retryReplay a FINISHED/FAILED/KILLED run with re-validated inputs (inputs removed since are dropped).
GET/api/v1/processes/{id}/langgraphLangGraph run status: thread id, per-node state, fan-out subs, traversed edges.
POST/api/v1/processes/{id}/resumeResume a failed LangGraph run from its checkpoint.
GET/api/v1/artifactsStream one artifact file; carries X-Process-Status and X-File-Complete.
GET/api/v1/artifacts/listList a run's artifacts (capped, with a truncated flag).
GET/api/v1/questionsQuestions by status or process, paged, with dispatch annotations.
POST/api/v1/questions/{id}/answerAnswer an open question and fire any bound dispatch.
GET/DELETE/api/v1/dispatches[/{id}]List newest first (status, agentName, limit default 100 and max 1000, offset; the reply carries total), inspect and cancel ask-and-dispatch records; secret parameter values come back masked.
GET/DELETE/api/v1/continuations[/{id}]List newest first (status, agentName, limit default 100 and max 1000, offset; the reply carries total), inspect and cancel completion continuations; secret parameter values come back masked.
GET/api/v1/costsRolling LLM harness (Claude/Codex/opencode) spend windows plus configured caps (admin).
GET/api/v1/costs/monthlyPer-agent spend for one UTC month from the persistent ledger (admin).
GET/api/v1/costs/totalsAll-time per-agent spend (admin).
GET/api/v1/costs/by-tag/{key}Spend per value of one configured subject-tag key; key must be in costTrackedTagKeys; secret and removed-key values are excluded (fail-closed); truncated flags a total summed from fewer than all matching runs (admin).
GET/api/v1/stream/processesSSE: status and command transitions plus question events.
GET/api/v1/stream/processes/{id}/llm-eventsSSE: canonical LLM events of a run, live or finished, resumable.
GET/api/v1/stream/processes/{id}/logsSSE: live stdout/stderr tail, resumable via Last-Event-ID.
GET/api/v1/stream/agentsSSE: agent reload diffs (added / updated / removed).
POST/api/v1/callback/questionsWorkspace callback: ask a question (per-process token).
GET/api/v1/callback/questions/{id}Workspace callback: read or long-poll the answer (waitSec).
POST/api/v1/callback/dispatchesWorkspace callback: register an ask-and-dispatch.
POST/api/v1/callback/runsWorkspace callback: dispatch now, optionally with a continuation.
POST/api/v1/callback/joinsWorkspace callback: parallel fan-out with one join continuation.
POST/api/v1/callback/tagsWorkspace callback: declare a runtime subject tag on the run (homer-tag).
GET/api/v1/callback/results/{token}Fetch an oversized result behind a capability token.
GET/api/v1/callback/whoamiWorkspace callback: which run and agent hold a callback token, for an egress proxy deciding per agent (any method; one 401 otherwise).
POST/api/v1/runner/registerRunner protocol: register a pull-mode runner instance in the domain the token belongs to (201; 422 bad tags/concurrency, a name or a non-blank version outside the tag shape, or a name already held by a live instance of the domain; 429 at maxInstances). Runner domain token (runners.*.token); 401 for every apiAuth credential.
DELETE/api/v1/runner/instances/{id}Runner protocol: deregister an instance (204; 404 unknown or foreign id).
POST/api/v1/runner/instances/{id}/claimRunner protocol: long-poll for a run to execute (200 session, 204 nothing or instance draining, 404 unknown or foreign instance id, 429 too many polls).
POST/api/v1/runner/sessions/{sid}/nextRunner protocol: report the previous op's result and long-poll for the next op (200 op, 204 nothing, 400 malformed body, 404 unknown session, 429 more than 3 polls open on the session — the reported result is still recorded).
GET/api/v1/runner/sessions/{sid}/ops/{opId}/tarRunner protocol: fetch the gzip'd tar of an upload op (200 stream; 404 unknown or finished op; past transferTimeoutSec the stream is cut off, its 200 already sent; 429 another fetch of the op in flight).
POST/api/v1/runner/sessions/{sid}/ops/{opId}/tarRunner protocol: post the gzip'd tar of a download op (?kind=dir|file; 202; 400 bad kind; 404 unknown or finished op; 408 past transferTimeoutSec; 413 over maxTransferBytes compressed or decompressed; 422 a refused entry (escaping, or a mode that cannot be normalized); 429 another post of the op in flight).
POST/api/v1/runner/sessions/{sid}/ops/{opId}/outputRunner protocol: append one output chunk (?stream=stdout|stderr&seq=N; 202; 400 bad stream or seq; 404 unknown or finished op; 408 past transferTimeoutSec; 409 out of order; 413 over 1 MiB; 429 another chunk of the op and stream in flight).
POST/api/v1/auth/loginExchange username + password for a session cookie.
POST/api/v1/auth/logoutClear the session cookie (idempotent).
GET/api/v1/auth/meYour username, role and grants — the console's capability source. The auth/* routes exist only with a !<password> scheme.
POST/mcpMCP endpoint exposing opted-in agents as tools (both MCP routes only with server.mcp.enabled).
POST/mcp/questionsMCP question tools for a running command.

Server-sent events http

Four read-only streams, each filtered to what the caller may see, with a heartbeat comment every 15 s to survive proxies. At most 100 open streams per caller across the four; the next is 429. Single-instance only.

curl -N "$HOMER/api/v1/stream/processes" -H "Authorization: Bearer $T"

Resumable log tail http

Tails one command's stdout or stderr as it is written; reconnect with Last-Event-ID to resume from a byte offset. It follows the command's actual artifact paths, so a per-attempt artifactNameTemplate still tails the attempt that is running.

curl -N "$HOMER/api/v1/stream/processes/12345/logs?cmd=0&stream=err"

Unified error model http

Validation failures map to typed statuses at one boundary: 400 input, 422 schema / depth / cycle, 429 cost caps and cooldowns, 409 a question or dispatch no longer open, 503 at capacity. A slot, queue or lock refusal is not an HTTP error: the call returns its process id and the run ends FAILED. 5xx bodies never echo internals.

{ "err": 1, "msg": "Invalid limit parameter. Must be between 1 and 1000" }
14 — MCP

Homer as a tool server

A stateless Streamable HTTP MCP endpoint on the same port, so an LLM client can start runs, poll them, read artifacts and cancel them.

Enable the endpoint server config

Off by default. When on, it sits behind the same authentication as the REST API.

server:
  mcp: { enabled: true, maxWaitSec: 300, maxInlineArtifactBytes: 65536 }

Expose an agent as a tool agent.yaml

Per-agent opt-in. The tool's arguments come from the agent's inputs and inputSchema; header inputs are never exposed, and an agent with a required header input is skipped — an MCP client could never supply it.

mcp:
  enabled: true

Connect a client mcp client

Any Streamable HTTP MCP client. The tool list is rebuilt per request and filtered by run grant, so reloads show up immediately.

{ "mcpServers": { "homer": {
    "type": "http", "url": "http://localhost:8080/mcp",
    "headers": { "Authorization": "Bearer your-token" } } } }

Blocking tool calls mcp

Every agent tool takes an optional _wait (seconds, clamped server-side): without it the call returns {runId, status} at once, with it you get final status, cost and artifacts.

{ "name": "deploy", "arguments": { "service": "checkout", "_wait": 120 } }

Run-management tools mcp

Always registered, visibility-gated like the REST routes they mirror.

get_run_info · list_artifacts · get_artifact · cancel_run

Question tools mcp

A separate endpoint authenticated by the per-process callback token, for the command that is running right now.

ask_user · check_answer · ask_user_and_wait · ask_and_dispatch · ask_and_dispatch_group · check_messages
15 — Authentication & authorization

Who may do what

apiAuth is required — running without it needs the explicit !<unsecured> opt-in. Every principal then declares role: admin or a list of grants.

Authorization: Bearer principal = the token's config key HMAC signature header principal = hmac:keyId session cookie + CSRF principal = session:username authenticate 401 unknown or invalid credential principal ci · hmac:github · session:alice authorize role: admin OR hasAction(principal, action, agent) checked in the handler — never by parsing the path GRANT = { agents: [ glob ], actions: [ … ] } run · read · control · edit · debug — debug is never implied by a wildcard 403 forbidden a missing action on an agent route, file routes without edit, admin-only ops (except cron-run: 404) 404 not found an agent with no grant (run · debug · inspect), a process outside admin ∪ owner ∪ read grant, or a control/run action missing on a visible run 200 allowed the run is stamped with its owner, inherited by every sub-run SEPARATE CREDENTIAL DOMAIN HMR_CALLBACK_TOKEN reaches /callback/* for its own process only NESTED HOP A → B allowed iff the root principal holds run on B, or agentGrants[A] reaches B — re-resolved live denied: RunAgent exit 255 · dispatch FAILED · registration 404
How a request becomes a permitted action. The split that catches people is on the right: 403 is for an action you lack on an agent route (run, debug, files) for an agent you can already see, 404 is for anything you may not see — a process outside your visibility, or an agent you hold no grant on when you run, debug or inspect it, is deliberately indistinguishable from a missing one, so nothing leaks by probing names or ids. A control or run action you lack on a run you can see (kill, retry, resume, answer, cancel) is a 404 too. The agent-file routes answer 403 before any lookup, which leaks nothing either. Note also what carries no authority: an agent definition. A hop from one agent to another is re-checked against operator-controlled grants, which is why edit on an agent cannot be escalated into running someone else's.

Bearer tokens server config

Named tokens for CLI, CI and MCP callers. Unknown token → 401; valid token missing the action on an agent route → 403, or — on the run, debug and LangGraph-inspect routes — 404 when it holds no grant on the agent at all. A missing control/run action on a run it can see (kill, retry, resume, answer, cancel) is 404.

apiAuth: !<bearer>
  tokens:
    admin: { token: "@SYSENV:ADMIN_TOKEN", role: admin }
    ci:    { token: "@SYSENV:CI_TOKEN",
             grants: [{ agents: ["deploy-*"], actions: [run, read] }] }

HMAC webhooks server config

Verifies a signature over the body (and optionally method, path, query, timestamp). Header, prefix, algorithm, encoding and payload template are configurable, covering Vikunja-, GitHub- and Stripe-style signatures.

apiAuth: !<hmac>
  keys:
    github:
      secret: "@SYSENV:GH_SECRET"
      signatureHeader: "X-Hub-Signature-256"
      prefix: "sha256="
      grants: [{ agents: [handle-github-push], actions: [run] }]

Replay protection server config

With a timestampHeader Homer enforces freshness and rejects a signature presented twice inside the window. The template must MAC-bind the timestamp, or startup fails.

timestampHeader: "Stripe-Signature-Timestamp"
payloadTemplate: "{{timestamp}}.{{body}}"
replayToleranceSec: 300

Password & session cookies server config

bcrypt-hashed users for browser clients; login mints an HttpOnly signed cookie. Generate hashes with the CLI — never store plaintext.

apiAuth: !<password>
  users: { admin: { passwordHash: "@SYSENV:ADMIN_HASH", role: admin } }
  sessionSecret: "@SYSENV:HOMER_SESSION_SECRET"   # ≥32 chars
  sessionTtlMin: 720
  # console on another origin: cookieSameSite: none + cookieSecure: true (HTTPS)

Session-secret rotation server config

Accept the old key on read while signing with the new one, then drop it after the TTL elapses — no forced logout.

sessionSecret: "@SYSENV:NEW_SECRET"
sessionSecretPrevious: "@SYSENV:OLD_SECRET"

Combined schemes server config

Console on cookies, CI on bearer, webhooks on HMAC — from one deployment. At most one of each, no nesting.

apiAuth: !<combined>
  schemes: [ !<password> {…}, !<bearer> {…}, !<hmac> {…} ]

Unsecured mode server config

Explicit opt-out of authentication, logged loudly at startup. Development and trusted networks only.

apiAuth: !<unsecured> {}

Grants and actions server config

Five actions over glob-matched agent names: run, read, control, edit, debug. debug is never implied by a wildcard.

grants:
  - { agents: ["deploy-*"], actions: [run, read, control] }
  - { agents: ["*"],        actions: [read] }

Visibility rules authz

A run is visible to admin ∪ its owner ∪ a read grant on its agent. Lists and SSE streams are filtered; single-resource denials return 404 so existence stays hidden.

GET /api/v1/status/999 → 404   # exists, but not yours

Nested-dispatch authority server config

Agent files carry no authority of their own. An A → B hop needs the root principal's run grant on B, or an operator-declared delegation.

server:
  agentGrants:
    router: [{ agents: ["worker-*"], actions: [run] }]

Per-process callback tokens runtime

A separate credential domain: HMR_CALLBACK_TOKEN authorizes only its own process's questions and dispatches, and operator credentials don't work there at all.

curl -H "Authorization: Bearer $HMR_CALLBACK_TOKEN" -H "Content-Type: application/json" \
     "$HMR_API_URL/api/v1/callback/questions" -d '{"text":"Proceed?"}'

CSRF guard for cookie auth console

Cookie-authenticated requests must carry a non-empty X-Homer-CSRF header (the console sends it automatically); token and HMAC callers are unaffected.

corsAllowedOrigins: ["https://console.example.com"]

CORS origins server config

Every entry must be a bare http(s)://host[:port] origin: a path, query, fragment, credentials or port 0 fails startup, and so does an entry that does not resolve to an origin. An entry may carry a @SYSENV: placeholder, resolved at startup like an auth secret, so the console's published port can come from the environment — and unlike globalEnv, a placeholder here does not mark the value secret. An empty list allows any host but never reflects credentials; pinned origins are what enable credentialed CORS.

corsAllowedOrigins: ["http://localhost:@SYSENV:FRONTEND_PORT"]

Rate limiting server config

Layered buckets: a global ceiling, a per-identity bucket on secured routes, a stricter per-IP one on login under an aggregate login ceiling, and one per runner domain. Login requests, and runner requests carrying a valid domain token, use their own buckets instead of the global one, so draining it cannot lock operators out or stall run pickup. The /livez and /readyz probes bypass all of them and never answer 429, so a drained bucket cannot make the kubelet restart the pod. Raise a configured limit to effectively disable it; the per-domain runner bucket is sized from the runner config, not set here.

server:
  rateLimit:        { limit: 1000, refillPeriod: 60 }
  perCallerRateLimit: { limit: 300, refillPeriod: 60 }
  loginRateLimit:   { limit: 30,  refillPeriod: 60 }   # default 5; raise behind a proxy

Request and file caps server config

Bounds on what a caller or an agent can multiply: body size, artifact size, config-file size and per-command output.

server:
  maxRequestBodyBytes: 10485760
  maxArtifactBytes:   104857600
  maxConfigFileBytes:   1048576
  maxOutputBytes:      10485760
16 — Observability & cost

Traces, spend, logs

Every run is a trace, every command a span. Claude, Codex and opencode spend is metered per attempt into a durable ledger that also backs the caps.

request cost cap check trailing 60 s global trailing 24 h per agent run proceeds LLM attempt (claude/codex) priced: spend endpoint, else CLI figure failed billable attempts count too 429 — no tokens spent cost ledger append-only in SQLite · survives restarts the next request reads this window span per command trace named for the agent · usage and cost details attached · secrets redacted → Langfuse over OTLP, or stderr SOFT THROTTLE, NOT A CEILING concurrent requests can each pass and overshoot together a run already past the check always runs to completion
The loop is the point: spend recorded during one run is what refuses the next request. Two consequences follow. Because the check sits at the request boundary, a refusal costs nothing — no tokens, no process, no workspace. And because it reads a window rather than a reservation, simultaneous requests can each find room and collectively exceed the cap; tighten the number if you need a hard ceiling rather than a throttle.

OpenTelemetry export server config

Ship spans to Langfuse over OTLP, or to stderr (java.util.logging, not app.log) for local debugging. A blank Langfuse URL falls back to that log exporter. The resolved destination is logged at startup and a failed batch at WARN through Homer's own logger, so a collector that silently stopped accepting spans is visible in app.log — the LOG-mode spans themselves never land there.

The Langfuse exporter declares OTLP ingestion version 4 (x-langfuse-ingestion-version: 4), which is what makes a v4 server ingest a batch within seconds instead of minutes; a v3 server ignores the unknown header. A run's trace name and subject tags ride on every span it exports, not just the root, because v4 keeps no separate trace record and reads both off each observation — so a name or tag filter finds the whole run, generations included.

openTelemetryExport: LANGFUSE     # or LOG
langfuse:
  serverUrl: "https://cloud.langfuse.com"
  publicKey: "@SYSENV:LF_PUBLIC"
  secretKey: "@SYSENV:LF_SECRET"
  projectId: "cm0abc123"          # only needed for trace deep links

Per-agent trace muting agent.yaml

telemetry.export: OFF drops the whole trace for that agent's runs — root span and every descendant — on every start path, retry and debug included. It is what a once-a-minute watcher wants so its no-op runs stop burying the ones you care about. All or nothing per agent: OTel decides sampling when the trace starts, and at that moment an interesting run is indistinguishable from a dull one. A muted run has no trace link, but its status, artifacts and cost are unaffected.

telemetry:
  export: OFF     # default ALL

Run tags by subject agent.yaml · http

A run carries key:value subject tags describing what it ran over. tags.fromInputs names declared inputs whose values become paramName:value tags at start (also emitted as trace tags); tags.runtime lists keys the run may declare mid-run with the homer-tag helper. Tags are returned on every run's status and filter the list — ?tag=mr:15, repeatable and ANDed — so you can ask afterwards which runs touched a subject. A filtered-out run is simply absent, never 403. The filter honours the same secret screen as the status response: a tag whose value would be redacted from a run's display (a secret input) is not matchable via ?tag= for that run, so the count cannot confirm a guessed secret. Tag-filtered results are bounded at 10 000 matching rows; total reflects only that prefix in the order specified by ?order=, default descending. Values match ^[A-Za-z0-9._-]{1,128}$ (no /, so tag path-shaped subjects by numeric id); cardinality is unbounded, so tag ticket ids and numeric ids, never free text. The list a run exports as trace tags — its source followed by the fromInputs values — is capped at 20 per span: it is copied onto every span of the run, so an uncapped list would multiply the exported payload by the span count. The cap truncates rather than refusing the run, warning unless the agent's export is muted (telemetry.export: OFF exports nothing to warn about). (telemetry.traceTags is the deprecated alias for tags.fromInputs.) The bundled example/agents/tagged-run/ agent is the worked example: projectId and mr resolved from its inputs, and decision declared mid-run with homer-tag.

tags:
  fromInputs: [projectId, mr]  # → projectId:4711, mr:4211
  runtime: [decision]          # homer-tag decision:approved
GET /api/v1/status/all?tag=mr:15&tag=projectId:4711

Trace deep links http · console

With langfuse.projectId set, a run's status carries langfuseTraceUrl and the console's process detail shows a Langfuse link. Blank (the default) means no links — and setting it reveals your Langfuse server and project id to every principal that can see the run, though the URL grants nothing on its own.

GET /api/v1/status/12345
# { …, "langfuseTraceUrl": "https://cloud.langfuse.com/project/cm0abc123/traces/…" }

Named traces & priced runs telemetry

Traces carry the agent's name and the request source on every span (v4 reads them per observation); each !<claude>/!<codex> step's generation is named after the step's label and carries usage and cost details, priced from the CLI's figure (Claude) or your spend endpoint (either); an attempt that ends more than one turn (a background subagent finishing after the first result) splits its cost across its generations, so they sum to the attempt's charge, and a step that was killed or stopped at a turn limit still gets a priced generation, marked as an error. A Codex step with no spend endpoint configured carries usage only, no cost. Retry, resume and debug runs go through the same starter, so they are named and tagged, and honour telemetry.export: OFF, exactly like a normal start.

langfuse.trace.name = "pr-reviewer"   ·   generation "review-diff"   ·   langfuse.observation.cost_details

Trace propagation into the CLI claude · codex · opencode

The active span is handed to the Claude, Codex or opencode subprocess as OTEL_TRACE_PARENT, so CLI-emitted telemetry stitches into the same trace. No configuration.

# automatic when a span is active

Span attributes telemetry

Flat attributes to build dashboards and alerts on without parsing span content. Every command span carries cmd.type and command.label; a !<claude>/!<codex> span adds llm.cost_usd, llm.cost.source (session, cli or none), llm.cost.fallback_reason (alert on a non-empty value other than session figure pending with a non-session source to catch degraded figures — a settled background lookup lands on the step's llm_cost_settlement child span instead), llm.session_id, llm.usage.*, retry.attempts / retry.attempts.used and llm.escalation.tier. The full table is in app/SERVER.md § Span attributes.

llm.cost.source = "cli"
llm.cost.fallback_reason = "incomplete: figure not stable across polls"

Secret redaction in telemetry telemetry

Masked in span input/output across all command types, and in the LLM event stream (/llm-events): values of secret: true inputs, every globalEnv / env value the operator sourced from the host via @SYSENV: (a composite masks the bare credential too), and the per-process HMR_CALLBACK_TOKEN. Only a literal config value is left alone — Homer cannot tell a token from a URL. Redaction follows the flags the run recorded when it started, so a later edit cannot unmask what was already collected.

- { paramName: token, secret: true }        # → *** in spans
globalEnv: { API_TOKEN: "@SYSENV:MY_TOKEN" }  # → *** too

Cost caps server config

Rolling-window soft throttles checked at the request boundary: over-cap requests get 429 before any tokens are spent. Debug runs (POST /api/v1/agents/{name}/debug) are never capped — scope debug grants accordingly.

costLimits:
  globalUsdPerMin: 5.0
  perAgentUsdPerDay: { pr-reviewer: 50.0, nightly-batch: 200.0 }

Persistent cost ledger http · console

Every billable attempt is appended to SQLite, so windows and statistics survive restarts. Four read endpoints back the console's Costs page; the last is enabled by listing keys under costTrackedTagKeys (top level) and shows a key selector plus a per-value spend table, with a note under the total when it covers only the newest 10,000 tagged runs.

GET /api/v1/costs               # rolling windows + caps
GET /api/v1/costs/monthly       # per-agent, one UTC month
GET /api/v1/costs/totals        # per-agent, all time
GET /api/v1/costs/by-tag/{key}  # per subject-tag value; secret and removed-key values excluded (fail-closed)

Price from your LLM proxy server config

Behind a proxy the CLI's total_cost_usd is a list-price guess. llmPrice.sessionSpend asks your spend API for the session's real total after every attempt — including killed ones — and falls back to the CLI figure, marked as such, when it cannot. The step itself does not wait: it is recorded at once on the CLI figure (or on no figure, for Codex), marked session figure pending, and this poll settles in the background, replacing the figure when it answers (ADR-0089). A cancelled run skips the lookup, so a harness that reports no cost of its own (Codex) charges nothing for it.

Spend endpoints ingest asynchronously: with callsPath or the window keys set (callsPath is ignored when the window keys are set — the window's row count drives the poll instead), Homer re-polls at 0, 5, 15 and 30 s until the endpoint has ingested up to 1 000 of the calls the attempt made (adversarial inflation is bounded at the executor), or, for Codex, which has no call count, until two readings agree, and marks the figure incomplete if it never does, or, for Claude, always when the session made more than 1 000 calls (excess calls remain unconfirmed) — raise server.shutdownDrainSec above 30 s + 4 × timeoutMs (42 s at defaults), and terminationGracePeriodSeconds with it, so a SIGTERM cannot cut the accounting short.

An agent that resumes its session with --continue reuses one session id across runs, so the session-cumulative costPath figure would charge each run the running total of all earlier ones. Point the window keys (requestsPath, startedPath, requestSpendPath) at the endpoint's per-request rows to price each attempt from only the requests inside its own window, so the per-attempt charges sum to the session's spend.

llmPrice:
  sessionSpend:
    url: "https://spend.internal/api/session/{sessionId}"
    headers: { Authorization: "Bearer @SYSENV:SPEND_TOKEN" }
    costPath: "$.spend"
    callsPath: "$.calls"          # ignored once the window keys below are set
    requestsPath: "$.requests"
    startedPath: "$.started"
    requestSpendPath: "$.spend"

Two log streams ops

app.log is the application log, on stdout and as a rolling file; api.log is a rolling per-request access log (no query strings, health and SSE excluded).

HOMER_LOG_LEVEL=DEBUG
HOMER_LOG_DIR=/app/workspace
17 — Console

The supervisory web UI

A Next.js app that watches one Homer instance at a time over SSE, and can author agents in place. It hides controls you lack grants for — the backend still enforces them.

Live process monitoring console

Status, current command and log tail arrive over SSE, with the process list and detail repolling every 30 s as a fallback until the run (or every run listed) is terminal — an empty list keeps polling; a dropped event self-heals on the next fetch. Each flow summary in the list keeps its own 30 s poll even after its runs have all finished, so a run a continuation adds to the flow still shows up. / opens /processes, and a corner badge shows the console and backend versions.

CONSOLE_HOMER_API_URL=http://localhost:8080

API error states console

A page whose data query fails says why instead of loading forever: the API rejected the request (sign in, or check the console and backend auth configuration), cannot be reached — down, or blocked because corsAllowedOrigins does not list this console's origin — did not answer in time, sent a response the console cannot read, or has no such process. The process list, the process detail and the questions pages carry the state.

Process list filtering console

Narrow the run list by a searchable agent combobox, by status chips, by subject tag (click a tag chip on any run; several chips AND, each shows as a removable badge) or to the children of one run. The list defaults to the flat list of all runs, with a Root runs toggle for the roots view — one row per flow, showing that flow's run count, total cost and aggregate state (running / waiting on a question / failed / finished). Every filter, the sort order and the page offset live in the URL, so a filtered view is shareable and survives a reload, and the detail pages' back button returns to it. A Cost column shows each run's spend, and the filter row shows the total for the currently filtered/paginated page. A Start time column shows when the run began, and a Duration column shows how long the run has been going; the Commands column carries one square per command that executed — six to a line, each square naming its command, state and duration on hover (the still-running square names no duration yet). Status is a single icon, Kill and Retry are icon-only buttons, and the Runner column shows where each run executes; a run that failed before it started shows its stored reason beside the icon, and with a Kubernetes runner a banner reports the last orphan-pod sweep.

/processes?agent=pr-reviewer&status=WORKING,FAILED
/processes?tag=mr:15,projectId:4711   ·   /processes?parent=12345
/processes?view=roots

Process detail console

Status timeline, executions in run order with exit icons and durations, stdout/stderr viewers with a Live badge, artifact downloads, and Kill / Retry actions. A run that failed before it started shows its stored reason in a Failed before it started panel below the header. The header shows the run's subject tags as chips and its cost — taken from the ledger through the status API, so it is still there after the artifacts are purged — labelled proxy, CLI estimate or mixed by where the figure came from; each Claude, Codex or opencode step shows its own cost, source (not reported when the harness reported no cost and no session-spend endpoint answered), fallback reason, token usage and CLI session id. When langfuse.projectId is configured there is a link to the run's Langfuse trace. The agent name links to its agent detail page, with the agent's group beside it when the agent has one (read from the agent's current definition, so it can change or disappear on past runs). A run started by another run links to its parent, and a Child runs card lists the runs it started; a run inside a flow also links to its root run (Root run #N). A root run's page instead shows a flat Flow section listing every visible descendant in id order — agent, status, cost and parent — with a toggle that hides the orchestrator's own resume segments (runs of the same agent as the root). An open question can be answered inline, a Runner panel shows the backend that served the run — the operator-chosen alias to an admin, the generic backend type to anyone else — and, for a Kubernetes run, its pod and phase, the workspace purge time is shown, and Download Artifact opens a picker.

/processes/12345

Live LLM conversation view console

For a Claude, Codex or opencode step, renders the conversation from the server's canonical /llm-events stream — model, turn count, elapsed time and the in-flight tool call while live — then the completed run in the same inline view, with a status badge, token usage (reasoning tokens shown when reported) and the cost the step was charged (session-spend or CLI figure), or "not reported" when nothing priced it. The event buffer is capped at 5000 events and 16 Mi characters per step (oldest dropped, with an "Earlier events not shown" notice), and a single event over 64 Ki characters shows a note in place of its payload; an event oversized in an identity field (an id, name or model) becomes a generic error note instead. A frame whose event is missing or shaped wrong — a turn end without a status or usage, an assistant message without text — shows the same generic error note rather than being rendered.

Process detail → running command → "Show output"  ·  finished step: expand the execution → Conversation

Agents list & detail console

One card per agent with Run and Edit buttons and, for a scheduled agent, its next and last cron run. Reload rescans the agents directory and lists what was added, updated, removed or failed. An All tab plus one tab per distinct agent group (sorted by name) narrows the list, the selection living in the URL's group param; an agent with no group appears under All only. An agent's page shows its parameters and transformers, its LangGraph graph, and its run history.

/agents  ·  /agents?group=platform  ·  /agents/{name}

Costs console

An admin view of rolling-window spend against the configured caps, refreshed every 5 s, plus monthly, all-time and by-tag cost cards.

/costs

Run dialog & curl export console

Fills in an agent's declared query/body/header parameters, or hands you the equivalent curl command to copy. Each input shows its declared default and allowed values (a secret input's default and allowed values are never shown). The exported command targets the active instance's backend URL, includes the JSON body built from the form inputs and carries the auth header as a $HOMER_AUTH_TOKEN shell placeholder rather than the real token; for an agent whose body is defined by an inputSchema it notes that the body must be supplied manually.

Agents → Run → Export Curl

Agent editor console

Three panes: a file tree, a Monaco editor with schema validation on save, and a debug-run panel that executes a single command with editable env and params.

Agents → New agent → Edit

Questions & continuations inboxes console

Answer questions across every running process in one place, review which agent a dispatch will start, and cancel pending dispatches or continuations. Continuations that failed to fire are listed with their reason, so a follow-up agent that never started is not just a line in the server log. The continuations lists show the newest 100 and say how many more exist; the questions inbox shows the oldest 100 open questions with the same note, and the sidebar badge counts them all, as it does the pending continuations. The sidebar itself collapses to icons only — with the badges kept on the icon — from a toggle at its bottom, and remembers the choice.

/questions  ·  /continuations

Schedules overview console

An admin list of every agent with a cron field — expression, timezone, next and last run — sorted by whichever fires soonest. Each row's Run button fires the agent immediately with cron semantics (source cron, owner system:cron, no parameters), behind a confirmation step; the row's last run then links to the new process.

/schedules

Runners overview console

A read-only admin view of configured runners, registered pull-mode instances and the claim queue, refreshed every 5 s. Each pull-mode instance shows the version it registered with (“unknown” when it reported none), with an exclamation mark when that version differs from the Homer server’s, so an outdated instance is visible at a glance.

/runners

Workflow status overlay console

LangGraph runs render their graph with per-node state and per-sub progress dots inside the execution detail, live while the command runs, plus a Resume button in the header for a failed, killed or unknown run. Edges the run has actually taken are drawn green; a legend explains fixed vs conditional edges, and a node that can route back to itself carries a small loop on its right side. Clicking a node that dispatched sub-agent runs opens a popover listing them, linked to their agent and process. The console draws at most 200 nodes and 300 edges (labels truncate at 40 characters); a larger graph falls back to the node-status list. That cap is the console's, separate from the API's 200-node / 1000-edge bound.

Process detail → running command → "Show workflow"  ·  finished: expand the execution

Multiple instances console

One console can point at several backends: add an instance from the login screen (which toggles between Password and Token sign-in — Token only when CONSOLE_ALLOW_BEARER=true, which also makes Token the mode the form opens in), switch the active one from the header picker; bearer tokens are namespaced per instance. Sign-in itself is on only with CONSOLE_AUTH_ENABLED=true. An optional allowlist pins which backends may be entered at all (and the CSP connect-src with it). Opening a page without a session prompts you to sign in (no “session expired” wording) and returns you to that page afterwards.

Login → "Change" → add instance
CONSOLE_AUTH_ENABLED=true     # sign-in on (default false)
CONSOLE_ALLOW_BEARER=true     # also offer Token sign-in (default false: cookie-only)
CONSOLE_ALLOWED_API_ORIGINS=https://homer-a.example.com,https://homer-b.example.com   # optional allowlist

Runtime plugins console

Your own pages, without rebuilding the console: drop an ES module into public/plugins/ and it contributes a sidebar entry, owns its route subtree, brings its own framework (or none), and calls the Homer API through the console's authenticated client. Only same-origin paths load. A plugin runs with the operator's privileges in the console's origin, so that directory is the trust boundary — treat what lands in it like source you merged. Append @admin or an Action name to an entry and the console will not load that plugin for anyone who lacks the permission.

CONSOLE_PLUGINS=/plugins/cars.js,/plugins/costs.js@admin

Themes, including your own console

Light, Dark, System, Terminal and Windows 95 ship in the console, switchable from the header and remembered across sessions. An operator adds their own by dropping a stylesheet into public/themes/ and naming it in CONSOLE_THEMES — it joins the same dropdown, and its tokens are ordinary CSS custom properties (plus optional same-origin @font-face rules). Only same-origin .css paths load. A theme runs no code, but it restyles the console for everyone who uses it, so that directory is a trust boundary too. Name one entry as the light theme and one as the dark theme and the built-ins are replaced: the dropdown then offers only your themes plus System, which follows the OS colour scheme onto the named pair.

CONSOLE_THEMES=corp-light:/themes/corp-light.css,corp-dark:/themes/corp-dark.css
CONSOLE_THEME_MODES=light:corp-light,dark:corp-dark

Accessibility & CSP console

Targets WCAG 2.1 AA with axe checks in the test suite, and ships a strict per-request nonce CSP (relaxed only on the Monaco editor route).

npm run lint && npm test
18 — Operating & authoring

Running it, editing it, debugging it

One config file, a Docker stack, editor autocomplete, a local CLI, and a Claude Code plugin that teaches the agent format.

the console is a browser SPA — it calls the API from the browser, so CORS origins and the CSRF header are the backend's job browser console :3000 serves the app · CONSOLE_HOMER_API_URL homer :8080 config.yaml · REST · SSE · MCP ssh runner hosts kubernetes pods Langfuse OTLP config/ read-only agents/ read-only workspaces/ rw homer.db + WAL langgraph/ per owner these two must survive a restart — put them on real volumes PROBES /api/v1/livez always 200 — wire livenessProbe here /api/v1/readyz 503 while draining — readiness and proxies never point liveness at readyz: it restarts pods mid-drain COMPOSE one network · the two ports on loopback · JDWP is opt-in, loopback-only, unpublished dev · prod overlays layer on the base file; e2e is its own stack shutdownDrainSec ≤ terminationGracePeriodSeconds
What talks to what. The dashed path is the one that catches people during a first deployment: the console serves the app, but every API call is made by the browser, so pointing CONSOLE_HOMER_API_URL at an address only the container can resolve fails, and the backend — not the console — is what must allow the console's origin. The two amber volumes are the ones whose loss is silent: without them every restart discards process history, open questions and parked workflows.

Start the server cli

One YAML or JSON config file as the sole argument. Ships as a fat jar, a thin jar, or an installable distribution.

java -jar homer-<version>-all.jar config.yaml

Docker stack docker

Backend plus console in one compose file, which pulls the published release images from GHCR (HOMER_VERSION picks the release tag; each image ships for linux/amd64 and linux/arm64, is signed with cosign and carries SLSA provenance and a CycloneDX SBOM (ADR-0086); each release also publishes a -slim server image without the agent CLIs — Claude Code, Codex, opencode, Node.js, git — for a deployment whose agents run on pull runners, ADR-0094); development, production and build-from-source overlays stack on it, and the e2e suite is its own standalone compose stack. The homer-app image installs pinned Claude Code, Codex and opencode CLI releases, overridable with the CLAUDE_CODE_VERSION, CODEX_VERSION and OPENCODE_VERSION build arguments; the Claude Code pin must match server.requireClaudeCodeVersion. The dev overlay starts no debug listener: JDWP is opt-in, and the debug overlay binds the container's loopback and publishes nothing (attach through a tunnel); build with HOMER_DEBUG=1 (a build argument) to bundle agentdebug.

cp .env.example .env
echo "HOMER_ADMIN_TOKEN=$(openssl rand -hex 24)" >> .env
docker compose up -d          # console :3000, API :8080

Graceful shutdown server config

On SIGTERM /readyz flips to 503 while in-flight runs finish, up to the drain window. The window covers the runs those runs start — a !<agent> hop, a dispatch, a continuation fired by a run that just ended — and runs already waiting for a runner claim, which still get one; a new top-level start is refused with 503 (a manual cron-run fire swallows the refusal and still answers 204). Keep it below terminationGracePeriodSeconds, since a shutdown with such work in flight can use the whole window.

server:
  shutdownDrainSec: 30

Editor autocomplete tooling

Two JSON Schemas ship in the repo — one for the config file, one for agent definitions. Register the kaml tags so YAML tooling understands !<cmd> and friends.

# yaml-language-server: $schema=../../../app/schemas/homer-agent.schema.json

agentdebug CLI cli

Runs and inspects agents locally without the server — list, schema-validate, print the command plan, execute (optionally one command, dry-run, with a custom env file via --env, input values via --input <file>, or --keep-workspace to inspect it afterwards).

./app/agentdebug.sh --config config.yaml list
./app/agentdebug.sh --config config.yaml validate my-agent
./app/agentdebug.sh --config config.yaml run my-agent --dry-run --cmd 1
./app/agentdebug.sh --config config.yaml run my-agent --input input.env --keep-workspace

Password hashing cli

Generates the bcrypt hash that goes into the config; the plaintext never touches a file.

./app/agentdebug.sh hash-password --cost 12

Single-command debug runs http · console

Executes exactly one command of an agent with ad-hoc env and params. Requires the explicit debug action — a wildcard grant never implies it.

curl -X POST "$HOMER/api/v1/agents/my-agent/debug" \
     -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
     -d '{"commandIndex":1,"env":{"REGION":"eu-west"}}'

Authoring plugin for Claude Code tooling

The repo doubles as a plugin marketplace: the bundled skill teaches Claude the agent format and ships the schemas and reference doc.

/plugin marketplace add https://github.com/livesport/homer.git
/plugin install homer-authoring@homer

Architecture decision records docs

The ADRs record why each structural choice was made — error model, runners, auth schemes, dispatch, checkpoint scoping, record retention, the threat model, run tags, run pricing.

docs/adr/0047-security-by-design-and-threat-model.md
Security posture in one line. Homer runs untrusted-by-construction code holding credentials for callers with distinct grants: principals are a hard boundary, every caller-multipliable resource is bounded, and denials are indistinguishable from not-found.
19 — Questions

What people ask in week one

The things that trip up newcomers, answered from the shipped behaviour rather than the intent.

Is there a Claude Code plugin? tooling

Yes — the repo doubles as a plugin marketplace. homer-authoring bundles a skill that teaches Claude the agent format, plus copies of both JSON schemas and the format reference. The .git suffix matters: it makes Claude Code clone the repo instead of looking up a marketplace name.

/plugin marketplace add https://github.com/livesport/homer.git
/plugin install homer-authoring@homer
/plugin marketplace update homer     # after the format changes

Do I need Claude at all to use Homer? basics

No. Homer is an execution orchestrator first — plenty of useful agents are nothing but !<cmd> and !<script> steps. The claude and codex commands are optional, and each needs its own CLI installed on whichever runner executes the agent.

YAML or JSON? basics

Either, for both config and agents. YAML uses kaml's type tags (!<cmd>, !<bearer>); JSON uses a "type" discriminator. If your editor flags "unknown tag", register the custom tags — the repo README lists the full set for the VS Code YAML extension.

- !<cmd> { cmd: "echo hi" }        ≡  { "type": "cmd", "cmd": "echo hi" }

Why doesn't my pipe / $VAR / glob work? commands

Because !<cmd> executes argv directly — no shell is involved, so there is nothing to expand or pipe. Anything needing shell syntax belongs in !<script>.

- !<script>
  shell: bash
  content: 'cat data.json | jq .id > "$HMR_ARTIFACTS_DIR/ids.txt"'

The run returned 200 — why did nothing happen? basics

Execution is asynchronous. The HTTP response is always {processId}; success or failure shows up in the process status, not in the response. Poll status, subscribe to the SSE stream, or watch the console.

curl "$HOMER/api/v1/status/$PID"   # → FINISHED | FAILED | KILLED

Where should an agent write files it wants to keep? workspace

$HMR_ARTIFACTS_DIR. The working directory is deleted the moment the run ends (cleanAfterFinish defaults to true), while artifacts survive until purgeAfter elapses and are served over the API.

./report.sh > "$HMR_ARTIFACTS_DIR/report.md"

How do I get a value from one command into the next? data flow

Capture it with resultEnvParam, then read it as $VAR in a script (or {{VAR}} in a prompt). Captured values sit at the top of the env precedence stack, so they override everything for later commands.

- !<cmd>
  cmd: "git rev-parse HEAD"
  resultEnvParam: [{ src: STD_OUT, envName: SHA, transformer: !<pass> {} }]
- !<script> { content: 'echo building "$SHA"' }

I edited an agent and nothing changed agents

Agents load at startup and on reload. Hit the reload endpoint (or the console's Reload button) and read the result: an agent that fails schema validation, declares a reserved envName, has a malformed cron or duplicates another agent's name is skipped with an error rather than loaded.

curl -X POST "$HOMER/api/v1/agents/reload" -H "Authorization: Bearer $ADMIN_TOKEN"   # admin only

Can an agent ask me something while it runs? hitl

Yes. Shell commands use the homer-ask helper that Homer materializes into every workspace; a Claude command can use the MCP question tools instead. Both render in the console's Questions inbox, and waits are resumable.

ANSWER=$(homer-ask ask-and-wait "Deploy to prod?" --option yes --option no)

Can one agent start another? dispatch

Three ways: the !<agent> command, homer-dispatch from a shell step, or ask-and-dispatch (fires after a human answers). Only homer-dispatch and ask-and-dispatch targets (and continuation targets) must opt in with dispatch: { enabled: true }; !<agent> does not check it. Every hop is authorized against grants, and a cycle or depth overrun in an !<agent> chain is refused.

What survives a restart? operations

Processes, questions, dispatches, continuations and the cost ledger — all in SQLite. Runs that were still executing become UNKNOWN (their driving coroutine is gone), and their open questions expire. In containers, keep the database on a real volume or you lose all of it every deploy.

Can I run several Homer replicas behind a load balancer? operations

No. Locks, the SSE broadcaster, cost-cap windows and the orphan-pod sweep are all single-node; there is no pub/sub backplane. Scale by giving a node more capacity, or by running independent instances with their own databases — the console can switch between them.

How do I stop an agent burning money? cost

Three levels. Server-side costLimits refuse a run with 429 at the request boundary once the rolling window is at the cap (debug runs are never capped, so scope debug grants accordingly). Per-command, maxBudgetUsd and maxTurns bound a single Claude invocation. And an agent's cooldown bounds how often it may start at all, which is what actually stops a fast-failing scheduled agent from retrying forever.

costLimits: { globalUsdPerMin: 5.0, perAgentUsdPerDay: { pr-reviewer: 50.0 } }

How do I keep secrets out of the config file? security

Reference host environment variables with @SYSENV: — resolved at startup, missing ones fail the boot. Mark caller-supplied secrets secret: true so they are redacted in responses and telemetry. Reaching into the host with @SYSENV: also counts as declaring the value a credential, so those values are masked in spans; a globalEnv entry whose value is a literal is the one thing that is not, which is the reason to route credentials through @SYSENV:.

globalEnv: { API_TOKEN: "@SYSENV:MY_API_TOKEN" }

I get 404 for a process I know exists security

That is the authorization model, not a bug. A run is visible to admins, its owner, and holders of a read grant on its agent; everyone else gets the same 404 a missing process would return, so existence is never disclosed — and a missing control or run action on a run you can see is the same 404. Password-session users can check /api/v1/auth/me; for a bearer token, check that principal's grants in the server config.

Can I run one heavy step on another machine? runners

Yes — and you can choose the granularity. runner: on the agent sends the whole agent to an SSH host, a Kubernetes pod or an external runner machine; a !<runnerCmd> step sends just that one command, with explicit file sync in and out.

- !<runnerCmd> { runner: gpu-box, syncToRemote: [train.py],
                 execute: "python3 train.py", syncFromRemote: [model.bin] }

Do I need Kubernetes or Python? basics

Only if you use those features. Kubernetes matters only for the k8s runner; Python only for the !<langgraph> command type. A plain Homer install needs neither.

Can a webhook trigger an agent? auth

Yes — the HMAC auth scheme verifies a provider's signature over the request body (and optionally method, path, query and timestamp). Vikunja's body-only HMAC-SHA256 hex scheme matches the defaults once signatureHeader: X-Vikunja-Signature is set; GitHub and Stripe fit by adjusting the header, prefix and template.

signatureHeader: "X-Hub-Signature-256"
prefix: "sha256="

Why does the console say I can't edit an agent? console

Two possible reasons. Either you lack the edit grant on that agent, or the agent's directory isn't writable on disk — the agent list reports that as writable: false and the UI gates on it. Read-only mounts in production do this deliberately.

What do I need to build from source? development

JDK 25 for the backend — the system Java will not build it, so pin JAVA_HOME. The console is a normal Node/Next.js project.

export JAVA_HOME=$(/usr/libexec/java_home -v 25)
app/gradlew -p app :app:shadowJar
cd console && npm install && npm run build

Where do I look when something is wrong? operations

app.log for the application log (stdout, plus a rolling workspace/app.log in Docker), api.log for per-request access lines, the process's cmd_N.err artifact for the command's own stderr, and /api/v1/health for runner and sweep state.

docker compose -f docker-compose.yml -f docker-compose.build.yml -f docker-compose.dev.yml up   # dev overlay sets HOMER_LOG_LEVEL=DEBUG

Is any of this documented in the repo? docs

All of it. app/AGENT.md is the agent-format reference, app/SERVER.md the config reference, app/README.md the API reference, DOCKER.md the deployment guide, and docs/adr/ holds a decision record for each structural choice, explaining why each piece works the way it does. This page lives at docs/homer-feature-atlas.html and every main pipeline publishes it with the documentation site on GitHub Pages, so the published copy tracks the code.

No features match that filter.

Compiled from README, AGENT.md, SERVER.md, DOCKER.md, console/README.md and the ADR set

Released under the Apache License 2.0. Documentation for 1.43.0.