Overlay Agent Host

@layernorm/overlay-agent-host runs the same outbound-only bridge on a local computer, VPS, container, or managed sandbox. It persists command outcomes, remote sessions, adapter stream cursors, and unacknowledged events in SQLite, so restarting the host does not duplicate accepted work.

Node.js 24 or newer is required. Overlay's one-copy command supplies a pinned Node 24 runtime even when the machine's default node is older:

npx --yes --package node@24 --package @layernorm/[email protected] \
  overlay-agent-host connect <enrollment-code> \
  --server https://getoverlay.io \
  --kind vps \
  --run

The machine needs outbound HTTPS access to Overlay and durable storage for the state directory. It does not need an inbound port.

Browser enrollment writes a restartable config.json beside the private connection state. The credential remains in the mode-0600 connection store rather than the JSON file:

{
  "environmentId": "environment-id",
  "workspaceId": "workspace-id",
  "controlPlaneUrl": "https://example.com/api/v1/agent-environments/environment-id/host/",
  "credentialEnv": "OVERLAY_AGENT_HOST_CREDENTIAL",
  "stateDirectory": "/absolute/path/to/overlay-agent-host",
  "filesystem": {
    "mode": "selected_roots",
    "roots": ["/absolute/project-one", "/absolute/project-two"]
  },
  "adapters": [
    { "manifest": "codex" },
    { "manifest": "claude-code" },
    { "manifest": "hermes" }
  ]
}

The built-in manifests resolve to the exact, release-tested @agentclientprotocol/[email protected] and @agentclientprotocol/[email protected] packages. Hermes uses its official hermes acp stdio server and requires Hermes Agent 0.20.6 or newer. Install Hermes from the official Nous Research distribution, then verify it before enrollment with hermes acp --check. A custom ACP process can still use the explicit id, displayName, protocol, command, and args shape.

acpx engine and Overlay Cloud images

--engine acpx runs Claude Code and Codex through acpx's runtime instead of the host's direct ACP client. Overlay Cloud machines use it. The image they boot from is built by infra/agent-image/provision.sh in the Overlay repo; overlay-agent-host image-check verifies such an image (manifest version, pinned adapters installed, no credentials on disk) and runs automatically before connect --kind overlay_cloud.

Eve

Eve is connected through its supported eve/client session and durable NDJSON stream contract. Run the Agent Host beside the private Eve service and point the adapter at its loopback or private network URL:

{
  "id": "eve",
  "displayName": "My Eve agent",
  "protocol": "eve",
  "host": "http://127.0.0.1:3000",
  "bearerTokenEnv": "EVE_AGENT_TOKEN"
}

The equivalent enrollment form is:

npx --yes --package node@24 --package @layernorm/[email protected] \
  overlay-agent-host connect <enrollment-code> \
  --server https://getoverlay.io \
  --kind vps \
  --adapter eve \
  --eve-url http://127.0.0.1:3000 \
  --eve-auth-env EVE_AGENT_TOKEN \
  --run

Overlay remains authoritative for approvals, commands, billing attribution, audit, and transcript projection. The adapter ignores private reasoning events, validates replies against Eve's pending input requests, and persists Eve's session ID, stream cursor, visible text, and usage accumulators for reconnects. Eve is pinned because its APIs are still preview. A missing cursor fails closed and requires start fresh. Eve connection OAuth pauses are not bridged; an authorization.required event fails the run closed instead of leaving it parked without an Overlay control.

Background and container operation

On macOS, install the per-user LaunchAgent after enrollment so the environment remains online when Terminal closes and returns after login or process failure. Use the exact config path printed by connect:

npx --yes --package node@24 --package @layernorm/[email protected] \
  overlay-agent-host service install --config "$HOME/.overlay/agent-host/config.json"
npx --yes --package node@24 --package @layernorm/[email protected] \
  overlay-agent-host service status --config "$HOME/.overlay/agent-host/config.json"

The installer records the current executable search path plus common user-level agent locations, so adapters installed in locations such as ~/.local/bin remain available after Terminal closes. service uninstall stops and removes only that environment's LaunchAgent. It preserves the credential, config, and SQLite state so the connection can be restarted later.

For a Linux VPS, create a dedicated overlay-agent system account, install the CLI globally, copy systemd/overlay-agent-host.service to /etc/systemd/system/, and place configuration under /etc/overlay-agent-host/. Adjust ReadWritePaths in the unit to exactly the project roots granted in Overlay, then enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now overlay-agent-host
sudo systemctl status overlay-agent-host

The unit restarts after process or machine failure and keeps state in /var/lib/overlay-agent-host. Upgrades are npm install -g @layernorm/overlay-agent-host@<version> followed by systemctl restart; do not delete the state directory. docker-compose.example.yml provides the same persistent, outbound-only shape for Docker. It exposes no host ports. Mount the approved workspaces and state volume, pull a pinned image version, and recreate the service to upgrade.

Run diagnostics and then the host:

OVERLAY_AGENT_HOST_CREDENTIAL=... overlay-agent-host doctor --config /absolute/path/config.json
OVERLAY_AGENT_HOST_CREDENTIAL=... overlay-agent-host run --config /absolute/path/config.json

Use {"mode":"all_user_files"} only when the user deliberately wants the harness to inherit all filesystem access available to the host OS account. Selected roots validate the working directory and ACP workspace roots; they are not an operating-system sandbox. For strict file isolation, run the host and harness under a restricted OS account, container, VM, or managed sandbox.

Native adapters such as OpenClaw are added only when the harness cannot expose ACP and only after the unchanged Agent Host conformance suite passes. Hermes uses its official ACP server. MCP remains a tool/resource protocol; it is not used as the execution lifecycle transport.

Durable lifecycle extension

Candidate 0.4.2 can opt in with OVERLAY_REMOTE_RUN_LIFECYCLE_VERSION=2 against a server that supports the same negotiated extension. Keep this unset against older servers. Live reattachment, session loading, interrupted-turn continuation, approval restoration and provider checkpoints are separate capabilities. ACP/acpx session history alone cannot restore an interrupted turn. Unknown/orphaned execution needs inspection before another writer can start. Upgrade only idle/drained hosts; do not restart active non-restorable work.

Streaming uses a durable background outbox with byte-budget uploads and coalesced text. Checkpoints exceeding one upload are visibly shortened; completion continues. Never rewrite attempted sequences on retry. Upgrade only idle/drained hosts.

An ACP/acpx adapter (including a manifest entry) may opt into guarded native recovery with fencedSessionRestoration: true in its private configuration. This requires durableLifecycle: true on the host and defaults off. Use it on owned native acceptance machines first; enable it on other hosts only after the adapter has passed native recovery acceptance. The server still requires isolation of the old provider, the original conversation identity, current authority and a startup acknowledgement; the option does not allow live interrupted-turn continuation or restore pending approvals.