@benkovy/doh-host

Host-side connector runtime for DOH.

Role in the system

This process runs next to an OpenClaw host and creates an outbound, persistent WebSocket connection to the DOH backend.

It is responsible for:

• host authentication handshake (host.hello -> backend.challenge -> host.proof -> backend.ready)
• receiving downlink relay commands (relay.send, relay.history.request)
• publishing uplink events (relay.event)
• publishing history responses (relay.history.response)
• reconnect behavior when network drops

Why this exists separately from the plugin

Keeping the connector as a standalone package/process allows:

• cleaner deployment and observability
• independent versioning and rollout
• option to reuse connector logic in non-plugin host integrations

The OpenClaw plugin package (@benkovy/doh) can wrap or invoke this connector behavior.

Environment variables

• DOH_RECONNECT_INITIAL_MS (optional)
• DOH_RECONNECT_MAX_MS (optional)
• DOH_RECONNECT_FACTOR (optional)
• DOH_RECONNECT_JITTER (optional)
• DOH_RECONNECT_MAX_ATTEMPTS (optional, 0 = unlimited)

Runtime identity and adapter settings are persisted in ~/.doh-host/config.json.

Adapter-specific environment can be defined under adapter.env in that config.

For the pi adapter, config also supports:

• adapter.tools (optional, defaults to read, write, edit, bash)
• adapter.skills
  • dir (default ~/.agents/skills)
  • include (optional skill directory names to include)
  • exclude (optional skill directory names to exclude)
  • enableModelLoad (optional, default true; exposes load_skill tool)
  • enableSkillMetadataPrompt (optional, default true; includes available skill metadata in prompt)
  • maxLoadsPerTurn (optional, default 2; limits load_skill calls per turn)
  • maxSkillBytes (optional, default 65536; max bytes for loaded SKILL.md and reference budget)
• adapter.env provider settings
  • PI_MODEL as provider/modelId (or PI_PROVIDER + PI_MODEL_ID)
  • provider API key env vars (for example OPENAI_API_KEY, ANTHROPIC_API_KEY)

Skill commands are always enabled for the pi adapter:

• /skill:<name> [args] loads the named skill immediately and appends optional args as user request context.

When a loaded skill includes references/*.md, doh-host includes those markdown references in the injected prompt block (subject to byte budget limits).

When using adapter.name = "pi", doh-host synchronizes a built-in doh skill into adapter.skills.dir on every startup (overwriting doh/SKILL.md and its references/*.md files).

Optional process env overrides are still used for reconnect tuning and state dir:

• DOH_STATE_DIR
• DOH_RECONNECT_INITIAL_MS
• DOH_RECONNECT_MAX_MS
• DOH_RECONNECT_FACTOR
• DOH_RECONNECT_JITTER
• DOH_RECONNECT_MAX_ATTEMPTS

Init workflow

CLI help:

doh-host --help

doh-host supports self-serve bootstrap provisioning:

doh-host init --email [email protected]

Or using token directly:

doh-host init --token <token-from-email>

Machine-readable mode:

doh-host init --token <token-from-email> --json
doh-host status --json

Configure pi model and API key:

doh-host config set-model --model openai/gpt-4o-mini
doh-host config set-api-key-env --provider openai --value <OPENAI_API_KEY>

After init completes, runtime config is written to:

• ~/.doh-host/config.json

init writes config only. Start runtime explicitly with doh-host run.

To run with existing env vars/config only:

doh-host run

To inspect runtime/config state:

doh-host status

To probe live backend auth handshake and selected adapter health:

doh-host status --probe

To clear local host config state and restart onboarding:

doh-host reset --yes

Machine-readable reset output:

doh-host reset --yes --json

Invite commands

Use invites to grant client access:

doh-host invite create --email [email protected]
doh-host invite list --limit 50
doh-host invite revoke --invite-id <inviteId>

Pi E2E smoke test

After bootstrap and config:

doh-host status --probe
doh-host run

In a second terminal:

doh-host invite create --email <client-email>

Then log in from the client app with the invited email and send a test message.

No command defaults to run mode.

LLM/Agent setup

Recommended agent-driven onboarding sequence:

1. Run doh-host init --email <user-email>
2. Prompt the user to paste the bootstrap token from their email
3. Run doh-host init --token <token>
4. Run doh-host run
5. Verify backend health reports at least one host connection

The runtime config file is written to ~/.doh-host/config.json.

Process adapter architecture

doh-host runtime now uses a process adapter interface so core relay logic is decoupled from any specific host process implementation.

Current default adapter is pi.

Reserved adapter name:

• pi: in-process adapter implementation

All other adapter names are treated as external socket adapters and must connect to:

• adapter.socketPath from config, or
• default ~/.doh-host/adapter.sock when adapter.name !== "pi" and no socket path is provided.

Adapter responsibilities:

• send(...): process user messages and return assistant output
• getHistory(...): return session history
• listSessions(...): return session summaries
• optional run lifecycle callbacks (start/end/error)

Core doh-host responsibilities (adapter-independent):

• backend auth handshake/reconnect
• relay envelope translation and publish semantics
• runtime lock/single-process enforcement
• invite APIs and host-authenticated backend HTTP calls
• local UI bundle store and bundle response handling

External adapters communicate with doh-host over Unix socket JSONL request/response frames. If no external adapter is connected, runtime continues and relay requests fail with adapter-unavailable events until an adapter connects.

DOH history is persisted in a local SQLite store at:

• ~/.doh-host/history.sqlite

The store is written directly during relay.send processing (pending -> sent/failed + assistant reply), so mobile history remains stable even if OpenClaw session maintenance prunes transcript artifacts.

On success/failure, the connector publishes corresponding relay.event entries for observability.

Development

pnpm --filter @benkovy/doh-host dev

Security notes

• API key secrets are host-machine secrets, never client-facing
• handshake uses nonce/challenge HMAC and timestamp checks in current scaffold
• always use TLS (wss://) in non-local environments

Runtime diagnostics

Connector logs are emitted as JSON lines and distinguish:

• transport events (connector.open, connector.closed, connector.error)
• auth events (auth.challenge.received, auth.ready, auth.error)
• reconnect behavior (connector.reconnect_scheduled, connector.reconnect_exhausted)

Release smoke checklist

Before and after publishing @benkovy/doh-host, run this quick checklist:

1. doh-host status --probe reports backend and adapter probes as ok.
2. Backend health (/health) reports hostConnections > 0 while doh-host run is active.
3. Send a message from client and confirm assistant reply arrives (relay.send.accepted).
4. Restart mobile app and verify history reloads without duplicated rows.

Next implementation steps

1. Add reconnect resume with server-issued session token
2. Add message idempotency tracking and ack/nack handling
3. Add optional health endpoint wrapper for supervisor integrations
4. Add dedicated Gateway transport health probing for startup diagnostics