Scout
DocsBlogToolsContact
Browse Docs

Core Concepts

QuickstartInstall ScoutArchitectureAgents & CollaborationConceptsIntegrating AgentsOperator AttentionSet up Scout for SlackSearch past agent sessions

Walkthroughs

Scout walkthroughs01 · Hello Scout02 · Your first ask03 · Choosing the runtime04 · A known crew05 · Keep track of agent work06 · Group work07 · Handoffs and reviews08 · Scout remembers09 · Everywhere you are10 · How Scout sees agents11 · The broker contract12 · Adding a harness

Integrations

Scout for Grok BotHost integrationsMCP APIA2A and ACP readiness

Scout Chat

Invite an agentScout Chat integrationsScout Chat HTTP APIScout Chat agent recipes

Implementation

Activity IndexingCodex App Server HarnessTelegram Bridge OwnershipNative Runtime

Proposals

Proposal · Collaboration Agreements

Agent Paths

scout.jsonagent.mdagents.mdllms.txtllms-full.txtnav.jsoninstall.mdthis page.md
Building on Scout01 / 03~3 min

10 · How Scout sees agents

Actors, endpoints, sessions — and the own-versus-observe boundary.

View MD

Goal

Understand the records Scout keeps about agents — actor, endpoint, session — and the boundary between what Scout owns and what it only observes.

You need

01–05 done. Read alongside architecture.md and concepts.md.

The idea

Three layers, kept distinct on purpose:

  • Actor/agent — the durable, addressable identity: kind: "agent", a handle, capabilities, a home node. Cards crystallize this layer.
  • Endpoint — where that agent is reachable right now: a transport (tmux, claude_stream_json, codex_app_server, ACP stdio, pairing bridge…), a node, liveness, and the session ids the harness reports.
  • Session — one harness-native context: the actual conversation a Claude or Codex process is holding. Sessions attach under the durable project/agent/profile data; they are execution state, not identity.

The rule that makes routing safe: identity is durable, sessions are disposable. An ask can name a project, a profile, or an agent and get a fresh session; only an explicit session: or --ref continues a specific one.

Walk it

Inspect the layers live

scout who --json # actors and their last activity
scout ps # configured local agents = endpoints you own

Bring a worker up (scout up . --harness claude --name probe), then look at its record: the endpoint carries sessionBacked, source, and — once the harness attaches — externalSessionId, the provider's own session id.

Watch adoption happen

A freshly spawned session starts pending: pendingExternalSession: true. When the harness process reports in, Scout binds the observed session id to the endpoint — the Scout routing id stays stable while the harness id becomes an alias. For a short window the broker trusts what it provisioned; after that, only observed runtime is authoritative. (This is the pending-launch trust window in runtime-sessions.md↗.)

See host detection

scout env

Scout detects which coding agent hosts it is running inside via environment markers — Cursor exports CURSOR_AGENT, Claude Code CLAUDECODE, Devin sets CHISEL_SESSION_DB. This is how whoami resolves the right sender from an agent-spawned shell. Treat vendor markers as contracts; undocumented ones get guarded matching.

How to tell it worked

  • You can point at a who entry and say which fields are identity and which are current endpoint state.
  • A scout up worker's endpoint goes pending → observed as its harness attaches.

Push further

  • scout session intake <harness> <id> gives an existing harness session a Scout-owned terminal home — adoption in the other direction.
  • Read specs/terminal-session-intake-surfaces.md↗ for why harness session identity and terminal backends are separate nouns.
  • The observation boundary is a hard rule: harness transcripts are source material, never bulk-imported as Scout messages (08).

Next

11 — The broker contract: the records Scout owns, who may write them, and the ask flow end to end.