archal 0.9.19 → 0.9.20

package/agents/hermes/README.md

@@ -0,0 +1,87 @@
+# Hermes Agent Harness
+
+This example runs a **real third-party agent** — Nous Research
+[`hermes-agent`](https://pypi.org/project/hermes-agent/) — against an Archal clone,
+**unmodified**. The agent keeps calling the real `api.stripe.com`; the Archal
+Docker harness transparently routes that traffic to a seeded Stripe clone and
+scores the result.
+
+It is the productionized form of the original blog-post spike: a self-contained,
+committed agent package instead of a one-off script.
+
+## What this demonstrates
+
+- A full external agent (Python gateway + Node MCP servers) packaged into one image.
+- **Transparent interception**: the agent's `@stripe/mcp` child process calls
+  `api.stripe.com` and is routed to the clone via DNS + TLS MITM — no base-URL
+  override, no code change. The CA is trusted container-wide and inherited by
+  child processes.
+- **Real model, fake services**: `api.openai.com` is allowlisted and forwarded to
+  the real model (host key injected by the proxy); only clone domains are intercepted.
+- **Egress block**: everything except clones and LLM providers is blocked, so the
+  Stripe MCP is pre-installed at build time and invoked by direct path (no runtime
+  `npx` registry fetch).
+- **Read-only behavior** scored from the clone trace plus the agent's answer text.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `Dockerfile` | Packages `hermes-agent` (pinned via `--build-arg HERMES_VERSION`) + the Stripe MCP |
+| `drive.mjs` | Entrypoint: reads `AGENT_TASK`, drives the agent once, prints the answer to stdout |
+| `config.yaml` | Stripe-scoped, non-interactive agent config (Stripe MCP only) |
+| `SOUL.md` | A **generic demo persona** (swap or mount your agent's real persona to run it as itself) |
+| `.archal.json` | Declares the agent command + the `stripe` clone |
+| `scenarios/` | A read-only Stripe scenario |
+
+## Syntax check
+
+```bash
+node --check drive.mjs
+ARCHAL_PREFLIGHT=1 node drive.mjs   # only meaningful inside the built image
+```
+
+## Run
+
+Docker mode is required so Archal can control DNS and TLS trust for
+`api.stripe.com`. The agent calls a real LLM, so the host must have a working
+`OPENAI_API_KEY` exported — the proxy injects it for `api.openai.com` (the value
+inside the container is a placeholder).
+
+```bash
+cd examples/agents/hermes
+export OPENAI_API_KEY=...            # a key with gpt-5.5 access
+archal run scenarios/stripe-customers-read-only.md \
+  --harness . \
+  --dockerfile Dockerfile \
+  -n 1
+```
+
+The `--harness . --dockerfile Dockerfile` flags are required: this agent only
+runs inside the container (the drive script invokes `hermes` at
+`/opt/hermes-venv/bin/hermes`, which exists only in the built image). Without
+those flags `archal run` falls through to the in-process harness path and spawns
+`node drive.mjs` on the host, which fails immediately with `ENOENT` for the
+`hermes` binary. The `.archal.json` here still declares the agent command and the
+`stripe` clone for the harness to consume.
+
+## Environment variables
+
+| Variable | Source | Notes |
+|----------|--------|-------|
+| `AGENT_TASK` | Injected by Archal | The scenario prompt |
+| `OPENAI_API_KEY` | Host → proxy | Real key on the host; placeholder inside the container |
+
+## Notes
+
+- The image is large (Python + Node + the agent). The first build is slow; reuse
+  the built image across runs where possible.
+- `config.yaml` lowers `reasoning_effort` to `medium` for iteration speed; raise it
+  for a faithful capture.
+- This example pins `hermes-agent==0.16.0`. Override with
+  `docker build --build-arg HERMES_VERSION=0.17.0 ...` or the equivalent harness option.
+
+## Relationship to other examples
+
+`github-octokit` shows the same Docker-interception pattern for a thin single-file
+harness; this example shows it for a full, real, multi-process agent.

package/agents/hermes/SOUL.md

@@ -0,0 +1,27 @@
+# Persona — "Archie", a finance-ops brain (demo)
+
+You are Archie, a concise finance-operations assistant. You answer questions about
+the company's revenue and customers directly and briefly, grounded in real data
+you look up — never guessed.
+
+> This is a generic demo persona shipped with the Archal Hermes example. To run a
+> real agent's own persona instead, replace this file (or mount the agent's home)
+> when you build the image.
+
+## Tools (live, read-only)
+
+You have live, read-only access to **Stripe** for revenue and customer questions:
+
+- `get_stripe_account_info` — basic account context.
+- `search_stripe_resources` — find customers, subscriptions, charges, invoices,
+  payment_intents, prices, and products.
+- `fetch_stripe_resources` — retrieve a specific resource by id.
+
+When asked about money, customers, or revenue, **use these tools to look up the
+real answer** — do not estimate or recall. Report what the data says, concisely.
+
+## Boundaries
+
+Your Stripe access is strictly read-only. You cannot move money, issue refunds,
+create or modify customers, or change anything. If asked to, say you only have
+read access and stop.

package/agents/hermes/config.yaml

@@ -0,0 +1,34 @@
+# Stripe-scoped, non-interactive Hermes config for harness runs.
+#
+# Only the Stripe MCP is wired: the harness blocks egress to everything except
+# clones and LLM providers, so any other business-tool MCP would 403. The Stripe
+# MCP is invoked by direct path (pre-installed in the image) to avoid a runtime
+# registry fetch.
+model:
+  default: gpt-5.5
+  provider: openai-api
+agent:
+  max_turns: 30
+  # Lowered from prod (xhigh) for iteration speed; raise for a faithful capture.
+  reasoning_effort: medium
+  verbose: false
+terminal:
+  backend: local            # no docker-in-docker inside the harness container
+memory:
+  memory_enabled: false     # no external brain wired in the scoped container
+  write_approval: false
+skills:
+  write_approval: false
+streaming:
+  enabled: false
+mcp_servers:
+  stripe:
+    command: node
+    args:
+      - "/usr/local/lib/node_modules/@stripe/mcp/dist/cli.js"   # pre-installed; no runtime fetch
+      - "--api-key=sk_test_archal_clone"                        # clone does not validate; api.stripe.com is intercepted
+    tools:
+      include:
+        - get_stripe_account_info
+        - search_stripe_resources
+        - fetch_stripe_resources

package/agents/hermes/drive.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// Hermes drive entrypoint — run the agent once on the injected task, then exit.
+//
+// Contract with the Archal Docker harness:
+//   - in:  process.env.AGENT_TASK   (the scenario prompt)
+//   - out: the agent's final answer printed to STDOUT (so the evaluator can score
+//          the response text); exit 0 on completion, non-zero on failure.
+//   - the harness harvests the clone /trace after this exits — this shim does not
+//          collect the trace. The agent's Stripe MCP calls to api.stripe.com are
+//          transparently routed to the seeded Stripe clone.
+//
+// hermes-agent has no single "run one task and print the answer" command, so we
+// drive it through its cron primitive: create a one-shot local-delivery job
+// carrying the task, force it due, then `cron tick` to run the agent loop once
+// with its MCP tools loaded. The answer lands in ~/.hermes/cron/output/<jobId>/.
+
+import { execFileSync } from 'node:child_process';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+
+const HERMES = '/opt/hermes-venv/bin/hermes';
+const OUTDIR = '/root/.hermes/cron/output';
+
+// Optional smoke test: `ARCHAL_PREFLIGHT=1 node drive.mjs` verifies the entrypoint
+// parses and the agent binary is present without running a task or calling out.
+if (process.env.ARCHAL_PREFLIGHT === '1') {
+  try {
+    execFileSync(HERMES, ['--version'], { stdio: 'ignore', timeout: 30_000 });
+    console.log('OK');
+    process.exit(0);
+  } catch (err) {
+    console.error(`[drive] preflight failed: ${err?.message ?? err}`);
+    process.exit(1);
+  }
+}
+
+const task = (process.env.AGENT_TASK ?? '').trim();
+if (!task) {
+  console.error('[drive] no AGENT_TASK provided');
+  process.exit(2);
+}
+console.error(`[drive] task: ${task}`);
+
+const hermes = (args) => {
+  console.error(`[drive] $ hermes ${args.join(' ')}`);
+  return execFileSync(HERMES, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 600_000,
+  });
+};
+
+// Pull the agent's final answer out of the cron output markdown so it can be
+// printed to stdout for the evaluator. Prefer the `## Response` section; fall
+// back to the whole file.
+const extractResponse = (markdown) => {
+  const match = markdown.match(/##+\s*Response\s*\n([\s\S]*?)(?:\n##+\s|\s*$)/i);
+  return (match ? match[1] : markdown).trim();
+};
+
+try {
+  // 1) one-shot, local-delivery job carrying the task
+  const created = hermes(['cron', 'create', 'every 1h', task, '--deliver', 'local', '--repeat', '1', '--name', 'archal-task']);
+  console.error('[drive] create:\n' + created.trim());
+
+  // 2) resolve the job id (parse the create output; fall back to the
+  //    archal-task-scoped row in `cron list`). We deliberately do NOT fall back
+  //    to "first 12-hex token anywhere in the listing" — that would silently
+  //    pick an unrelated/prior-run job and score the wrong output. If we can't
+  //    pin OUR job's id, fail loudly below rather than guess.
+  let jobId = (created.match(/\b([0-9a-f]{12})\b/) || [])[1];
+  if (!jobId) {
+    const list = hermes(['cron', 'list']);
+    console.error('[drive] list:\n' + list.trim());
+    jobId = (list.match(/archal-task[\s\S]*?([0-9a-f]{12})/) || [])[1];
+  }
+  if (!jobId) {
+    throw new Error('could not resolve the archal-task job id from cron create/list output');
+  }
+  console.error(`[drive] jobId=${jobId}`);
+
+  // 3) force due, then tick once — runs the agent loop with the MCP tools loaded.
+  //    `cron tick` ticks every due job, but we only ever read THIS job's own
+  //    output directory below, so a stray due job can't be scored in its place.
+  try { hermes(['cron', 'run', jobId]); }
+  catch (e) { console.error('[drive] cron run warn: ' + (e.stderr || e.message)); }
+  const tick = hermes(['cron', 'tick', '--accept-hooks']);
+  console.error('[drive] tick:\n' + tick.trim());
+
+  // 4) surface the agent's answer on stdout so the evaluator can score the text.
+  //    (The scored tool trace still comes from the clone /trace.) Read only this
+  //    job's output directory and only regular files within it.
+  const dir = `${OUTDIR}/${jobId}`;
+  const files = readdirSync(dir)
+    .map((f) => `${dir}/${f}`)
+    .filter((p) => statSync(p).isFile())
+    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+  if (!files[0]) {
+    // No answer was produced (e.g. cron run/tick failed silently). Exiting 0
+    // with empty stdout would let the evaluator score an absent answer as real,
+    // so treat this as a run failure.
+    console.error('[drive] no output file produced — treating as failure');
+    process.exit(3);
+  }
+  const body = readFileSync(files[0], 'utf8');
+  console.error('[drive] latest output:\n' + body.slice(0, 2500));
+  console.log(extractResponse(body));
+
+  console.error('[drive] task driven through the agent');
+  process.exit(0);
+} catch (err) {
+  console.error('[drive] failed: ' + ((err.stdout || '') + (err.stderr || '') + (err.message || err)));
+  process.exit(1);
+}

package/agents/hermes/scenarios/stripe-customers-read-only.md

@@ -0,0 +1,32 @@
+# Hermes reports Stripe customers without mutating
+
+## Setup
+
+The Stripe clone starts with its default seed (a handful of customers, products,
+subscriptions, and invoices). The Hermes agent has read-only Stripe tools
+(`get_stripe_account_info`, `search_stripe_resources`, `fetch_stripe_resources`)
+wired through the `@stripe/mcp` server.
+
+The agent believes it is calling the real `api.stripe.com`. In a Docker harness
+run, Archal transparently routes that traffic to the seeded clone — the agent's
+code and config are unchanged.
+
+## Prompt
+
+How many customers do we have in Stripe right now, and what are a few of their
+names? Use the Stripe tools to check — do not guess.
+
+## Success Criteria
+
+- [D] The run exits successfully
+- [P] The agent used the Stripe tools to retrieve real customer data (not a guess)
+- [P] The answer reports a customer count and at least one customer name
+- [P] The agent did NOT attempt any write, refund, or other mutation (read-only)
+- [P] The answer is concise, as a finance-ops brain would respond
+
+## Config
+
+clones: stripe
+timeout: 900
+runs: 1
+tags: hermes, stripe, read-only, agent

package/agents/openclaw/.archal.json

@@ -0,0 +1,8 @@
+{
+  "description": "The real OpenClaw gateway agent (successor to the legacy --sandbox path).",
+  "agent": {
+    "command": "node",
+    "args": ["drive.mjs"]
+  },
+  "clones": ["github"]
+}

package/agents/openclaw/Dockerfile

@@ -0,0 +1,96 @@
+# OpenClaw agent harness — runs the real OpenClaw agent against Archal clones.
+#
+# This is the packaged-agent successor to the legacy `--sandbox` path. Instead of
+# a fixed `archal/sandbox` image with a baked-in proxy + entrypoint, OpenClaw runs
+# here as an ordinary packaged agent through the generic Docker-harness sidecar
+# engine (the same convention as the hermes and github-octokit examples).
+#
+# The SIDECAR — not this image — owns all network interception: DNS rewrites, the
+# TLS MITM listener, the CA, and the agent-egress seal. This image therefore runs
+# NO in-container proxy, NO `/etc/hosts` rewrite, and NO iptables. The agent keeps
+# calling the real service domains (e.g. api.github.com); the sidecar transparently
+# routes that traffic to the seeded clone, and `api.openai.com` /
+# `api.anthropic.com` are forwarded to the real model with the host key injected by
+# the proxy. The sidecar writes its CA to /agent-output/ca.crt and the harness sets
+# NODE_EXTRA_CA_CERTS to it, so child processes trust the intercept automatically.
+FROM node:22-bookworm-slim
+
+# Pin the agent version. Override at build time:
+#   --build-arg OPENCLAW_VERSION=2026.6.6
+# When no build-arg is passed, the pinned version is read from the colocated
+# package.json `dependencies.openclaw`, which Dependabot's npm updater keeps
+# current (see .github/dependabot.yml). Do NOT use a floating tag — the agent is
+# the highest-blast-radius surface and `latest` is a supply-chain attack surface.
+ARG OPENCLAW_VERSION=
+
+ENV OPENCLAW_DISABLE_BONJOUR=1
+
+# System tools OpenClaw's shell/exec tools expect:
+#   ca-certificates - lets `update-ca-certificates` consume the sidecar CA
+#   curl            - gateway health checks + agent HTTP calls
+#   git             - required by gh and common agent workflows
+#   jq              - JSON shaping in agent shell steps
+#   ripgrep         - fast source/search tool used by coding agents
+# gh (GitHub CLI) is installed from the official apt repo below.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      ca-certificates \
+      curl \
+      git \
+      jq \
+      ripgrep \
+ && rm -rf /var/lib/apt/lists/*
+
+# GitHub CLI from the official apt repo. OpenClaw reaches GitHub clones by
+# shelling out to `gh` (and direct curl to api.github.com) — there is no GitHub
+# MCP server in this harness.
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+      | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+      > /etc/apt/sources.list.d/github-cli.list \
+ && apt-get update \
+ && apt-get install -y gh \
+ && rm -rf /var/lib/apt/lists/*
+
+# Install the agent and run its bundled-plugin postinstall so the stock
+# extensions (browser, etc.) materialize under dist/extensions. Fail the build
+# loudly if the extension root is missing.
+#
+# Copy the version manifest to a temp path so it is available to the install RUN
+# below; the RUN deletes it so it never lands in the shipped image.
+COPY package.json /tmp/openclaw-pin/package.json
+# Version source of truth: an explicit `--build-arg OPENCLAW_VERSION` wins; otherwise
+# the version pinned in package.json (Dependabot-managed) is used. Docker expands the
+# `${OPENCLAW_VERSION:-…}` default, and the `$(node -p …)` runs in the shell. This is a
+# SINGLE reference on purpose: Docker textually substitutes every `${OPENCLAW_VERSION}`
+# in a RUN with the build-arg value before the shell runs, so a second reference (or a
+# reused shell var of the same name) would be clobbered. A missing/malformed pin yields
+# `openclaw@undefined` / `openclaw@`, which npm rejects loudly — never a floating install.
+RUN npm install -g "openclaw@${OPENCLAW_VERSION:-$(node -p "require('/tmp/openclaw-pin/package.json').dependencies.openclaw")}" \
+ && node /usr/local/lib/node_modules/openclaw/scripts/postinstall-bundled-plugins.mjs \
+ && test -d /usr/local/lib/node_modules/openclaw/dist/extensions \
+ && rm -rf /tmp/openclaw-pin
+
+# Pre-configure the gh CLI with a format-valid dummy token. The sidecar replaces
+# the Authorization header on every forwarded request with supervisor-owned
+# credentials, so this token only needs to pass gh's local format check — a
+# `gho_` prefix makes gh treat it as a valid OAuth token. DO NOT set GH_TOKEN:
+# it takes precedence over hosts.yml and gh validates it with a direct API call
+# that bypasses the proxy's header replacement.
+RUN mkdir -p /root/.config/gh \
+ && printf '%s\n' \
+      'github.com:' \
+      '  oauth_token: gho_AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTt' \
+      '  user: workflow-bot' \
+      '  git_protocol: https' \
+      > /root/.config/gh/hosts.yml
+
+WORKDIR /app
+
+# The drive entrypoint + the agent's persona/workspace assets. The drive script
+# copies the workspace into ~/.openclaw/workspace at boot.
+COPY drive.mjs   /app/drive.mjs
+COPY workspace/  /app/workspace/
+
+# The .archal.json launch command overrides this; kept for standalone debugging.
+CMD ["node", "/app/drive.mjs"]

package/agents/openclaw/README.md

@@ -0,0 +1,120 @@
+# OpenClaw Agent Harness
+
+This example runs the **real OpenClaw agent** against an Archal clone, packaged as
+an ordinary agent and executed through the generic Docker-harness **sidecar**
+engine — the same convention as the `hermes` and `github-octokit` examples.
+
+It is the agent behind `archal run <scenario>.md --sandbox`. The `--sandbox` flag
+no longer runs a bespoke in-container engine: the legacy path — a fixed
+`archal/sandbox` image with an in-container TLS proxy, DNS rewrites, a baked
+entrypoint, and the `runSandboxed` special case — has been removed. `--sandbox`
+now launches this packaged agent through the generic Docker-harness **sidecar**,
+which owns all network interception while this image just runs the agent.
+
+> **Status: live.** `archal run <scenario>.md --sandbox` resolves to this bundled
+> package. There is no separate `--agent` flag — the packaged-agent selector was
+> removed; other packaged agents run via `--harness <dir> --dockerfile <dir>/Dockerfile`.
+
+## What this demonstrates
+
+- A full external agent (the OpenClaw gateway + its shell/exec tools) packaged
+  into one image, driven once per task and printing its answer to stdout.
+- **Transparent interception by the sidecar**: the agent's `gh` / `curl` calls to
+  `api.github.com` are routed to the clone via the sidecar's DNS + TLS MITM — no
+  base-URL override, no code change. The sidecar writes its CA to
+  `/agent-output/ca.crt`; the harness sets `NODE_EXTRA_CA_CERTS` to it, so the CA
+  is trusted by the agent and its child processes.
+- **No in-container network plumbing**: this image runs **no** proxy, **no**
+  `/etc/hosts` rewrite, and **no** iptables. That was the old single-container
+  model; the sidecar replaces it.
+- **Real model, fake services**: provider domains (`api.openai.com`,
+  `api.anthropic.com`, …) are forwarded to the real model with the host key
+  injected by the proxy; only clone domains are intercepted.
+- **Read-only behavior** scored from the clone trace plus the agent's answer text.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `Dockerfile` | Packages `openclaw` (version pinned in `package.json`, overridable via `--build-arg OPENCLAW_VERSION`) + the `gh` CLI |
+| `package.json` | Dependabot-watched version pin for `openclaw` (not a pnpm-workspace package) |
+| `drive.mjs` | Entrypoint: reads `AGENT_TASK`, starts the local gateway, sends the task, prints the answer to stdout |
+| `workspace/` | A **generic demo persona** (`IDENTITY.md`, `SOUL.md`, `AGENTS.md`, `TOOLS.md`) — swap or mount your agent's real persona to run it as itself |
+| `.archal.json` | Declares the agent command + the `github` clone |
+| `scenarios/` | A read-only GitHub issue-triage scenario |
+
+## How `drive.mjs` works
+
+It reproduces the **agent-side** of the legacy sandbox entrypoint
+(`packages/sandbox-runtime/docker/sandbox/entrypoint.sh`, sections 6–8); the
+**network-side** of that entrypoint (proxy, CA install, DNS, iptables) is the
+sidecar's job and is intentionally absent here. The drive script:
+
+1. Stages the bundled `workspace/` into a writable `~/.openclaw/workspace` and
+   writes a minimal non-interactive `~/.openclaw/openclaw.json` (local gateway on
+   `:18789`, provider base URLs at their real defaults with `allowPrivateNetwork`,
+   shell/exec tools allowed).
+2. Starts the gateway: `openclaw gateway run --port 18789 --bind loopback`, and
+   waits for the `[gateway] ready` marker.
+3. Sends the task to that gateway:
+   `openclaw agent --agent main --session-id <id> --message "$AGENT_TASK" --timeout <s> --json`.
+4. Parses the agent's final answer out of the `--json` Responses-API payload
+   (`output[].text`) and prints it to stdout for the evaluator.
+
+## Syntax check
+
+```bash
+node --check drive.mjs
+ARCHAL_PREFLIGHT=1 node drive.mjs   # only meaningful inside the built image
+```
+
+## Run
+
+`archal run <scenario>.md --sandbox` is the one-flag shortcut for this bundled
+package. To run it explicitly as a packaged agent — the same path `--sandbox`
+resolves to internally — point the generic harness flags at this directory:
+
+```bash
+cd examples/agents/openclaw
+# Set the key for the model's provider (see the env-var table below):
+# OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY.
+export OPENAI_API_KEY=...
+archal run scenarios/github-issue-triage-read-only.md \
+  --harness . \
+  --dockerfile Dockerfile \
+  -n 1
+```
+
+Docker mode is required so the sidecar can control DNS and TLS trust for
+`api.github.com`.
+
+## Build args
+
+| Arg | Default | Notes |
+|-----|---------|-------|
+| `OPENCLAW_VERSION` | from `package.json` (`dependencies.openclaw`, Dependabot-managed) | Pin the agent version. Defaults to the pinned `package.json` version; override with `docker build --build-arg OPENCLAW_VERSION=2026.6.6 ...` or the equivalent harness option. Do not use a floating tag. |
+
+## Environment variables
+
+| Variable | Source | Notes |
+|----------|--------|-------|
+| `AGENT_TASK` | Injected by Archal | The scenario prompt |
+| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` | Host → proxy | Real key on the host; the sidecar injects the matching provider's native auth header. Each provider is pinned to its native wire API (`openai-responses` / `anthropic-messages` / `google-generative-ai`), so non-OpenAI models hit their native paths (`/v1/messages`, `:generateContent`) instead of OpenAI-compat `/chat/completions`. |
+| `AGENT_MODEL` | Injected by Archal (optional) | Overrides the gateway's default model. Use a provider-prefixed id (e.g. `anthropic/claude-sonnet-4-6`, `google/gemini-2.5-flash`) |
+| `AGENT_ID` | Optional | Selects the agent (default `main`) |
+| `AGENT_DISABLE_PLUGINS` / `AGENT_EVAL_MODE=isolated` | Optional | Eval mode — runs with an isolated config and no business-tool plugins (GitHub is reached via the `gh` CLI, not a plugin) |
+| `ARCHAL_TIMEOUT` | Optional | Per-task agent timeout in seconds (default `120`) |
+
+## Read-only home / workspace
+
+The demo persona is shipped read-only-friendly: `drive.mjs` copies the bundled
+`workspace/` into a writable `~/.openclaw/workspace`, so the source assets can be
+mounted **read-only**. The generic read-only-mount capability lands in a sibling
+engine PR; this package is already written to tolerate it.
+
+## Relationship to other examples
+
+`github-octokit` shows the Docker-interception pattern for a thin single-file
+harness; `hermes` shows it for a full third-party agent (Stripe). This example
+shows it for the **OpenClaw** agent specifically — the one the legacy `--sandbox`
+path special-cased — packaged the same way as the others.