Host integrations

OpenScout's core broker, runtime, protocol, CLI, desktop app, and mobile app live in this repository. Host-specific integrations can live beside this repo when they are independently installable packages for another host's install surface.

This keeps the OpenScout root focused on the product control plane while still making the integration surface discoverable.

Current Integrations

Compatibility Model

OpenClaw has an initial local session adapter↗ in @openscout/agent-sessions. It is not yet a broker-selectable harness or an OpenClaw plugin that exposes Scout tools.

Scout uses host integration as the umbrella term for first-class compatibility with another agent tool, terminal host, or IDE. A host integration can contribute one or more roles:

• execution harness: Scout can route work into a session backed by that runtime
• agent host: the tool can host a Scout-aware agent surface or plugin
• MCP host: the tool can connect to scout mcp
• terminal host: the tool can expose or control terminal panes that contain Scout-compatible sessions
• agent-state surface: the tool can report lifecycle, focus, approval, or session state around agents Scout cares about

harness remains the narrower runtime field. Claude Code, Codex, Cursor, Grok, and pi can be harness-backed execution targets. Hermes and Herdr are first-class host integrations, but they are not Scout harnesses: Hermes is an agent/MCP host, and Herdr is a terminal host plus agent-state surface. Do not add hermes or herdr to --harness or execution.harness unless an explicit execution adapter is implemented.

Shared Routing Guidance For Integrations

Every host integration should teach the same low-churn workflow:

1. Capability request: pass project directory plus optional harness/capability (projectPath + harness, or scout ask --project <path> --harness <rt>).
2. Broker dispatch: let Scout choose/wake/create a compatible worker instead of asking the user or agent to guess names such as claude.main.
3. Durable handle: display the returned ref, flightId, conversationId, workId, session id, and any broker-suggested situated target handle.
4. Follow-up: continue by that handle. Humans type saved situated targets as target:<name>; agents and compact UI may render the same handle as ⌖name.
5. Promotion: name or pin a long-lived sibling only after the routed worker is known good, preferably using the broker-suggested mnemonic.

Integrations should expose projectPath and harness in their ask surfaces where the host allows it. who/resolve/search remain useful for inspecting or disambiguating a specific target, but they are not a required preflight for project-routed work.

Hosted Assistants Using The Remote Client

The single-file client at landing/openscout.app/public/remote/scout is for assistants with a Python 3.8+ shell in a cloud VM. Install it using the remote installer↗. A host with native remote MCP OAuth support can use the gateway directly; a host with a secret broker can use the separate static-token path. Verify the host's actual transport before choosing a guide.

The CLI uses the existing MCP authorization server: scout login --as muse registers the client and prints an approval link. The operator chooses the Scout agent identity on the consent page and returns its one-time code#state value. scout login --code <code> checks state and exchanges the code with the PKCE verifier retained in the VM. --as names the client; the consent page is authoritative for the identity. Access credentials renew through the saved refresh token. Keep credentials and the verifier out of chat and logs.

Verify scout whoami against the chosen identity before scout who and a small authorized ask. Keep the receipt's flight id for scout wait or scout status. Follow-up work must use the exact returned session through the advertised ask schema (scout call ask supports JSON arguments); do not assume a fresh ask to the same agent retains the previous conversation. For an exact-session continuation, omit projectPath and to; use targetSessionId alone as the target. currentDirectory is optional caller context, not a second routing target.

SCOUT_TOKEN overrides saved credentials. Unset it before starting another login, otherwise subsequent commands would keep using the environment's identity. A successful login --with-token replaces the locally saved OAuth sign-in and pending login; a rejected token preserves them. Local logout removes saved credentials, but does not revoke a server grant or unset SCOUT_TOKEN. Static-token administration and OAuth grant revocation are different mechanisms; do not present mesh bridge token revoke as OAuth grant revocation.

Connection failures are not evidence that a machine is offline. The client retries only MCP initialization, at most three attempts, with fresh session headers. A dropped or truncated tool response is ambiguous: the tool may already have executed. Inspect any existing receipt before taking another action. A node_unreachable response specifically indicates that the gateway cannot reach the Scout bridge; inspect that bridge on the Scout machine.

An accepted ask, completed reply, and automatic incoming delivery are separate acceptance gates. A CLI response proves no ability to wake an idle hosted assistant. Do not install prompt-managed mailbox loops as onboarding. The host must support delivery into its conversation before automatic incoming messages can be promised.

Client regression checks: python3 -m unittest discover -s scripts -p test_remote_scout.py. These use synthetic credentials and local transport fixtures; they do not establish live Muse connectivity.

Relationship To This Repo

Use links and install docs rather than git submodules by default.

Submodules are useful when this repo must build, test, or vendor another repository at an exact commit. The current Scout host integrations do not need that coupling: they shell out to the installed scout CLI or talk to the local broker, and their compatibility boundary is the published Scout protocol and CLI behavior.

Keep integration source in a separate repository when:

• the host has its own plugin marketplace or install flow
• the integration can be installed without cloning OpenScout
• the package should have its own release cadence
• the integration depends on Scout's public CLI/protocol surface rather than private app internals

Keep integration source in this repository when:

• it depends on unreleased internal code
• it is still shaping the core protocol or broker API
• local product development needs cross-package changes in one commit

Local Development

Recommended sibling checkout layout:

~/dev/
├── openscout/
├── pi-scout/
├── claude-scout/
├── codex-scout/
├── cursor-scout/
├── hermes-scout/
└── herdr/

That layout keeps the product repo clean while making related host integrations easy to work on side by side.

Personal connection addresses

For owner-directed hosted-assistant onboarding, use a published https://oscout.net/{user} profile. The assistant requests access, displays a matching code, and privately completes login after the owner approves the same code in their inbox. See Personal Scout profiles↗ for visibility controls, the remote client command, notification limits, and rollout requirements.