Scion is a container-based orchestration platform for running multiple LLM "deep agents" concurrently, each isolated in its own container, workspace, and credentials. This document fixes the preferred term for each domain concept so that code, docs, UI, and prompts share one vocabulary.
Two naming rules run throughout: the concept formerly called grove is now project, and bare "broker" is never used on its own — it is ambiguous across three distinct concepts (Runtime Broker, Message Broker, and the Event Bus), so it must always be qualified (see the disambiguation rule under Hub & Hosted). The codebase does not yet fully match either rule; the known gaps are tracked as GitHub issues.
Agent: An isolated worker: one LLM-plus-harness loop in its own container with its own identity, credentials, and workspace. The fundamental unit of execution in Scion. Avoid: worker, bot, instance, process
Sub-agent: An agent spawned by another agent; "sub" only from the orchestrating user's view, since it is a full agent in capability. Avoid: helper, thread, worker thread
Project:
A namespace and collection of agents and configuration, represented by a .scion directory and usually one-to-one with a git repository.
Avoid: grove, group, repo, workspace
Template: A harness-agnostic folder resource defining a generic agent — its system prompt, agent instructions, skills, services, and more — containing nothing specific to any one harness. Templates can live locally (in project or global scopes) or be managed as fully fledged Hub-level resources (user, project, and global scopes) with CRUD, CLI, SDK, and Web UI support. A default harness-config may optionally be named, but is not required. Avoid: role, blueprint, profile, config See also: Harness-config (its harness-specific counterpart), Skill
Harness: The external, vendor-supplied agent software that Scion drives, such as Claude Code, Gemini CLI, Codex, or OpenCode. Provided outside Scion; Scion only configures and runs it. Avoid: model, backend, driver, tool See also: Harness-config
Harness-config: A named, reusable, harness-specific resource that configures a particular harness — which harness, plus its image, auth, secrets, model settings, and skills. The harness-specific counterpart to the (harness-agnostic) Template, and extensible the same way via a container-script provisioner rather than compiled-in logic. Avoid: harness, harness adapter, integration, plugin See also: Template, Harness, Container-script provisioner
Container-script provisioner:
The script-based provisioning model (provisioner.type: container-script) by which a harness-config extends agent setup with a container-side provision.py, making harness provisioning extensible — as opposed to a compiled-in (built-in) provisioner.
Avoid: built-in provisioner, plugin provisioner, install script, provision hook
Skill: A reusable, harness-agnostic instruction snippet contributed by a template and mounted into the harness's skills directory at provisioning. Follows the open Agent Skills convention. Avoid: prompt snippet, macro, plugin See also: Template, Plugin, Skill Bank
Skill Bank:
The Hub-backed system for publishing, versioning, resolving, caching, and federating Skills. Encompasses the scion skills CLI, the Hub Skill Registry, semver + content-hash resolution, and the skills web UI — as distinct from a plain template-mounted skill file.
Avoid: skill store, skill hub, skill catalog
See also: Skill, Skill Registry, Skill Reference URI
Skill Registry: The Hub-side store and resolver for the Skill Bank: it holds published skills and their immutable versions, resolves Skill Reference URIs, and can federate resolution to external registries (including GitHub and GCP Vertex AI sources). Avoid: skill repo, skill index See also: Skill Bank, Skill Reference URI
Skill Reference URI:
The addressing scheme for a Skill: a bare name or a skill://<registry>/<scope>/<scopeId>/<name>@<version> URI (with gh:// and gcp-skill:// variants for federated sources). Versions may be exact, a semver range, latest, or a sha256: content hash.
Avoid: skill path, skill locator
See also: Skill Bank, Skill Registry
Plugin:
An out-of-process extension built on hashicorp/go-plugin (gRPC) that supplies a Message Broker implementation without modifying Scion core. Harness implementations are not offered as plugins; additional plugin types may be added in future.
Avoid: extension, addon, module, skill
See also: Broker plugin, Message Broker
Pre-Start Hook:
A project-scoped or Hub-scoped shell script executed synchronously inside the agent container during initialization before the main harness starts up (via the EventPreStart hook point, staged at .scion/hooks/pre-start.d/30-project-custom). If the script exits non-zero, agent startup is aborted. Provides a blocking initialization mechanism for project owners and Hub administrators.
Avoid: startup script, provision hook, lifecycle script
sciontool: The helper utility injected into every agent container for status reporting, metadata access, and task management. Avoid: agent tool, scion-tool
Agent Port Forwarding: A feature that allows exposing local HTTP ports running inside an agent container through the Hub as authenticated, reverse-proxied URLs. Built on an outbound WebSocket reverse tunnel. Avoid: agent tunnel, port proxy, hub reverse tunnel, web access See also: sciontool
Runtime: The container technology that executes an agent's container: Docker, Podman, Apple Container, or Kubernetes. Avoid: backend, engine, executor, environment See also: Runtime Broker, Profile
Workspace:
The working directory mounted into a single agent's container at /workspace. How it is provisioned across a project's agents is set by the project's workspace sharing mode.
Avoid: project, repo, mount
Workspace sharing mode: How a project's workspace is provisioned across its agents — one universal set of modes intended for both local and Hub-managed projects: Shared-plain, Worktree-per-agent, and Clone-per-agent. Avoid: workspace mode, isolation mode
Shared-plain: A workspace sharing mode where one workspace directory is mounted into every agent with no per-agent isolation — the model used for plain (non-git) projects. Avoid: shared mount, plain workspace
Worktree-per-agent: A workspace sharing mode where each agent gets its own git worktree over a shared checkout, isolating working trees while sharing one clone's history. Supported in local mode today; not yet on Hub-managed projects. Avoid: worktree mode, shared checkout
Clone-per-agent: A workspace sharing mode where each agent gets its own full git clone of the repository. Avoid: clone mode, per-agent clone
Shared directory: A persistent, mutable volume shared by the agents within one project. Avoid: shared mount, shared volume, common dir
Agent home: The directory mounted as the container user's home folder, holding that agent's unique config and history. Avoid: home mount, config dir
Hub: The control plane of Scion — it owns identity, auth, project registration, and state, exposes the APIs and notifications that agents and users interact with, and dispatches commands to runtime brokers. Present in both workstation and hosted mode, not only hosted. Avoid: server, master, coordinator
Runtime Broker: A service that manages the lifecycle of containerized agents on behalf of the Hub — provisioning workspaces, hydrating templates, and delegating container operations to a pluggable runtime. Brokers vary along two dimensions: whether they require host-level access to a container runtime (node-bound vs. proxy) and whether they run as a standalone process or are embedded in the Hub. Always write in full; "broker" alone is forbidden because it collides with Message Broker. See also Managed Agent, which bypasses the broker entirely via a direct cloud API integration. Avoid: broker, node, runner, worker See also: Node-Bound Broker, Proxy Broker, Embedded Broker, Hosted Broker, Managed Agent, Runtime, Profile, Message Broker (distinct concept, same word)
Node-Bound Broker: A Runtime Broker that runs on the same compute node as the containers it manages. Required for runtimes that need direct host access, such as Docker (via the daemon socket) or Apple Container (via the Virtualization framework). A node-bound broker is inherently stateful — its identity is tied to the machine it runs on, and it connects to the Hub via a persistent control channel and periodic heartbeats. Avoid: local broker, host broker See also: Runtime Broker, Proxy Broker, Embedded Broker
Proxy Broker: A stateless Runtime Broker that delegates container operations to an API-mediated service such as Cloud Run or Kubernetes. Because it communicates over a network API rather than a local daemon, a proxy broker is not tied to any particular compute node and can be replicated for high availability. Avoid: remote broker, API broker, cloud broker See also: Runtime Broker, Node-Bound Broker, Hosted Broker
Embedded Broker: A Runtime Broker running inside the same process as the Hub server, eliminating control-channel overhead. Both node-bound and proxy brokers can be embedded. Contrast with a standalone broker, which runs as its own process and connects to the Hub remotely. Avoid: inline broker, in-process broker See also: Runtime Broker, Combo server, Hosted Broker
Hosted Broker: An embedded proxy broker that serves as the platform's default compute backend. Because it is both stateless and co-located with the Hub, it can be replicated alongside Hub instances for high availability without broker-specific scheduling. Agents dispatched without an explicit broker target are routed to it automatically. Avoid: default broker, platform broker, cloud broker See also: Runtime Broker, Proxy Broker, Embedded Broker
Managed Agent:
An agent whose lifecycle is managed directly by the Hub via a cloud provider API (e.g. Google Managed Agents), bypassing the Runtime Broker layer entirely. Managed agents share the same Manager interface and agent-label system as containerized agents, but have no container, no workspace mount, and no broker involvement. The choice between a managed agent and a brokered agent is a deployment-time decision controlled by a broker profile, not a property of the agent template.
Avoid: cloud agent, API agent, serverless agent
See also: Runtime Broker, Profile
Profile: A named bundle of runtime broker settings selected as a unit — a runtime plus its execution settings (env, volumes, resources), default harness-config and template, image registry, secrets, and harness overrides. A runtime-broker-scoped concept; long form Runtime Broker Profile. Avoid: environment, runtime config, preset, runtime profile See also: Runtime Broker, Runtime
Message Broker:
The pluggable system that brokers messages between Scion actors (agents and users) and messaging surfaces — built-in brokers such as the web UI Messages view, and broker plugins to external systems like Telegram, Discord, Slack, Google Chat, and Microsoft Teams. Backs the scion message command. Always write in full; "broker" alone is forbidden because it collides with Runtime Broker.
Avoid: broker, message bus, queue, pub/sub
See also: Broker plugin, Built-in broker, Plugin, Event Bus (distinct), Runtime Broker (distinct, same word)
Broker plugin:
A Message Broker implementation for a specific external messaging system (e.g. Telegram, Discord, Google Chat, Microsoft Teams), loaded through the broker plugin interface (PluginTypeBroker).
Avoid: connector, bridge, adapter
See also: Message Broker, Built-in broker, Plugin
Built-in broker: A Message Broker implementation shipped with Scion rather than loaded as a plugin — for example the broker that surfaces messages in the web UI's Messages view. Avoid: native broker, internal broker, default broker See also: Message Broker, Broker plugin
Disambiguation rule: Never use bare "broker" in prose, comments, docs, or new identifiers — always qualify it as Runtime Broker or Message Broker. Note that
pkg/broker(NATS-style pub/sub) is not the Message Broker; it underpins the Event Bus. Existing bare usages in code are tracked for cleanup as GitHub issues.
Event Bus:
The NATS-style pub/sub system (pkg/broker) that brokers and dispatches real-time change events to live web views via server-sent events, supporting the move to a more stateless Hub. Distinct from the Message Broker; currently a latent capability.
Avoid: message broker, broker, change feed, live sync, event stream
See also: Message Broker (distinct concept)
Hub-managed project:
A project whose workspace is created and managed by Scion in the hub-controlled part of the broker filesystem (~/.scion/projects/<slug>/), shared across the project's agents — as opposed to a Linked project that points at a pre-existing path. May be plain (no git) or git-backed; git-backed hub-managed projects may share a remote with other projects. The workspace itself is the Hub-managed workspace.
Avoid: hub-native, hub-native project, hub workspace, hub-project, hosted project, cloud project
Linked project: A project whose workspace is a pre-existing path on a broker machine, linked to a Hub for cross-broker visibility — as opposed to a Hub-managed project. May be plain or git-backed. Avoid: local project, imported project, registered project
Shadowed project: A local directory associated with a Hub project purely for CLI routing, with no workspace content, no provider registration, and no broker involvement — as opposed to a Linked project, whose workspace is a real pre-existing path on a broker machine. Avoid: linked, mounted, cloned See also: Hub-managed project
Server:
The scion server command group, and the single combined process it manages — one or more server components run together as a background daemon (or with --foreground) via start/stop/restart/status.
Avoid: daemon, service, backend
Server component: One of the roles a server process can run — the Hub API, the Runtime Broker API, or the Web dashboard. A single server process may run any combination of these. Avoid: service, module, role
Combo server: A server process running both the Hub and Runtime Broker components together (the default in workstation mode). Avoid: hub-broker, all-in-one, standalone, monolith
Secret:
A credential made available to an agent at runtime (e.g. API keys, tokens). A harness-config's secrets field declares which secrets an agent needs; the Secret Backend — a pluggable store (local SQLite for development, GCP Secret Manager in production, selected via SCION_SERVER_SECRETS_BACKEND) — stores and resolves them, scoped by user, project, runtime broker, or hub, and injects them into the container. Also holds the Hub's signing keys.
Avoid: credential, vault, secret store, env secret
See also: Harness-config, Profile
Port Forwarding: The feature that allows users, developers, and external systems to access HTTP services running inside agent containers securely via the Hub's reverse proxy. Requests are routed over a persistent, authenticated WebSocket-based reverse tunnel established from within the container to the Hub. Avoid: tunnel, docker proxy, ingress See also: Auto-Expose, Hub
Auto-Expose:
A sub-feature of port forwarding where sciontool periodically scans for listening TCP sockets inside the agent container (by reading /proc/net/tcp and /proc/net/tcp6), filters them by policy, and registers them with the Hub using the auto-scan label. Stale registrations are automatically cleaned up when the service stops listening.
Avoid: auto-port, automatic scan, port exposure
See also: Port Forwarding, sciontool
A2A Protocol: An open standard (developed by Google) for secure, structured communication between independent artificial agents. It defines a lightweight JSON-RPC 2.0 dialect over HTTP, alongside standard discovery mechanics ("Agent Cards") for advertising capabilities. See also: A2A Protocol Bridge
A2A Protocol Bridge: A standalone, self-managed service that translates standard A2A JSON-RPC payloads into Scion Hub API calls and vice versa. It exposes Scion agents as standard A2A-compliant JSON-RPC endpoints, enabling multi-agent orchestration, third-party platform integrations, and desktop client federation. Avoid: A2A bridge, A2A adapter, A2A proxy See also: A2A Protocol, Hub
Agent Authorization Role:
A named authority tier (one of none, readonly, baseline, or full) assigned to an agent that governs the API scopes granted in its Hub-issued JWT. Resolves via a two-gate authority lattice matching requested role, user ceiling, and project maximums.
Avoid: raw template scopes, agent scopes
See also: User Access Token (UAT)
Group: A named collection of Hub users (and nested groups) used by the Hub permissions system to assign access. This is the primary meaning of "group" in Scion. Avoid: team, org, role See also: Message Group (different concept — message recipients, not users)
User Access Token (UAT):
A scoped, revocable bearer token (prefixed with scion_pat_) linked to a user account and used for non-interactive Hub authentication (e.g., CLI, CI/CD pipelines, desktop app integration). Every UAT is scoped to a single project and carries a specific list of action permissions (scopes).
Avoid: personal access token (PAT), API key, secret token
See also: Hub
Quota System: An advisory-lock-based enforcement system that governs resource consumption at agent and project creation. It uses fail-closed semantics and prevents reservation leaks, operating on schemas including LimitDefinition, EntitlementBinding, and UsageReservation. Avoid: rate limits, usage caps
LimitDefinition: A seeded system or custom limit configuration that defines a quota boundary within the Quota System.
Branch mode (message mode): A message mode that permits messaging from ancestry users (like lineage) plus the agent's direct parent and child agents. Project owners can pierce branch mode. Avoid: tree mode, family mode
Lineage mode (message mode): A message mode that restricts messaging to users in the agent's ancestry chain — the creating user and their ancestors. No agent-to-agent messaging is permitted for lineage-mode agents. Project owners can pierce lineage mode. Avoid: ancestry mode, parent-only mode
Message Group:
A set of recipients addressed by a single send, correlated by a shared group_id, as opposed to a direct message to one recipient or a broadcast to all agents in a project.
Avoid: group, set, group chat, room, thread
See also: Group (different concept — hub users, not recipients)
Message Mode:
A per-agent setting that controls which actors (users and agents) can send messages to that agent. One of four values: none, lineage, branch, or project (the default). Set by the agent's owner or a project admin via the set_message_mode action; changeable at any time with immediate effect. Stored on the agent record as message_mode.
Avoid: messaging mode, communication mode, access mode
See also: Ancestry chain, Piercing
Messageability:
A server-computed assessment of whether a specific viewer can message a specific agent, considering the agent's message mode, the viewer's identity, ancestry relationship, and permissions. Exposed in API responses as _messageability with canMessage and canReachViewer booleans. Used by the UI to gate message buttons and show reachability indicators.
Avoid: reachability (acceptable in UI context but not as the canonical term)
Native Web Chat:
The built-in interactive messaging interface in the Web Dashboard (enabled via the web.native_chat feature flag) that promotes chat to a top-level fourth ShellType (alongside standalone, profile, and app). It features a dedicated thread rail, unread indicators, three-state visibility filtering (Conversation/Verbose/Full), @-mention autocomplete, and cross-channel reply coherence.
Avoid: chat plugin, external chat, messages tab (only for the old tab)
None mode (message mode): A message mode that seals the agent from all messaging except system-plane notices and super-admin piercing. No users and no agents can message a none-mode agent through normal paths. Avoid: sealed, quarantined (informal usage acceptable in UI confirmation dialogs, not in technical docs)
Notification:
An event delivered when an agent reaches a tracked trigger activity (e.g. completed, waiting_for_input, limits_exceeded). Recipients register a Subscription — scoped to a single agent or to a whole project, naming which trigger activities fire it and whether an agent or a user receives it. Backs scion notifications and the --notify flag on scion message.
Avoid: alert, event (for the notification), watch (for the subscription)
See also: Activity (notifications fire on activity values)
Piercing (message authorization): The ability of a privileged user to bypass an agent's message mode restrictions. Super-admins pierce all modes including none. Project owners pierce lineage and branch modes. Piercing applies only to user identities — it is never inherited by an owner's agents. Avoid: override, bypass (too generic)
Project mode (message mode):
The default message mode. Any user with the agent:message permission in the project scope can message the agent, and any same-project agent in project or branch mode can message it. The most permissive mode.
Avoid: open mode, public mode
Project ID: A project's unique identifier — always a randomly generated UUID. A git remote is associated metadata, not identity, so multiple projects may share the same remote by design. Avoid: grove ID, project key, repo ID, slug
Ancestry chain:
The tracked root → parent → child relationship between agents that governs transitive access control.
Avoid: lineage, hierarchy, agent tree, family
Phase:
The infrastructure lifecycle stage of an agent container, from created through running to stopped or error.
Avoid: status, stage, lifecycle state
See also: Activity (what the agent is doing, vs. its container stage)
Activity:
What a running agent is currently doing, such as thinking, executing, waiting_for_input, or blocked. Distinct from phase.
Avoid: status, state, mode
See also: Phase (the container stage), Blocked (a specific activity value)
Blocked: The activity an agent assigns to itself when intentionally waiting for an expected event, so it is not mistaken for stalled. Avoid: stalled, stuck, idle, waiting See also: Activity (Blocked is one of its values)
The run modes form a spine of increasing infrastructure — Local → Workstation → Single-node hosted → HA hosted. Two independent dimensions separate them: the availability tier of the control plane (whether the Hub runs as a single instance on an embedded database, or is replicated across an external one), and Tenancy (whether it serves one user or many). Tenancy is orthogonal and only opens up once hosted; the availability tier is fixed by the Hub's database driver (SCION_SERVER_DATABASE_DRIVER: sqlite vs. postgres).
| Mode | Control plane | State & durability | Tenancy | Canonical use |
|---|---|---|---|---|
| Local mode | None (CLI only) | Local machine; git-worktree isolation | Single-user | Agents launched directly via the scion CLI, no server |
| Workstation mode | Combo server (Hub + Runtime Broker + Web) on loopback | Embedded SQLite on that machine | Single-user | The hosted experience locally, on your own machine |
| Single-node hosted | One networked Hub instance on a single node | Embedded SQLite, local/single-volume; non-HA | Single- or multi-user | A cheap, simple networked Hub — a single VM, or a single Cloud Run instance + SQLite |
| HA hosted | Hub replicated behind a load balancer | External managed DB (Postgres) + object storage; highly available | Single- or multi-user | A durable, always-on shared deployment — Cloud Run + Cloud SQL |
Local mode:
Running Scion with no server at all — agents launched directly via the scion CLI, with state on the local machine and isolation via git worktrees.
Avoid: solo mode, standalone mode, single-user mode, workstation mode
Workstation mode: Running a single-tenant Scion server (Hub + Runtime Broker + Web combined) on your own machine, giving the hosted experience locally over loopback. A local server, not the no-server CLI workflow. Avoid: local mode, local server, dev mode, single-user mode
Hosted mode:
The umbrella term for running against a networked Hub — reachable beyond a single machine — that coordinates state across users, projects, and runtime brokers. Spans two availability tiers, Single-node hosted and HA hosted, distinguished by control-plane durability and cost; the tier is fixed by the Hub's database driver (embedded sqlite vs. external postgres). Orthogonal to the tier is Tenancy (single- vs. multi-user).
Avoid: hub mode, cloud mode, distributed mode, production mode
See also: Single-node hosted, HA hosted, Tenancy, Workstation mode
Single-node hosted:
A hosted deployment whose control plane — the Hub — runs as a single instance on one compute node, keeping state in an embedded SQLite database on local or single-volume storage, with no external database. Non-HA: it accepts restart/redeploy downtime and single-volume durability in exchange for low cost and operational simplicity — there is no separate database to provision, secure, back up, or pay for. Realized as a single VM (e.g. the starter-hub scripts, scripts/starter-hub/) or a single Cloud Run instance backed by SQLite. "Single-node" scopes the control plane only — agents may run on other nodes. The sqlite driver pins the Hub to one instance (a single DB connection and in-memory lifecycle-hook deduplication).
Avoid: single-instance hosted, standalone hosted, lite hub, sqlite mode
See also: HA hosted, Hosted mode, Tenancy, Node-Bound Broker (broker-to-node binding — a different subject, same word "node")
HA hosted:
A hosted deployment whose control plane is replicated across multiple Hub instances behind a load balancer, backed by an external managed database (Cloud SQL Postgres) and object storage (GCS), with stateless proxy/hosted brokers. Highly available and durable — it survives node loss and redeploys without downtime — at the cost of running and paying for that external infrastructure. Realized by the Cloud Run deployment (scripts/cloudrun/: Cloud Run with min-instances ≥ 2 plus Cloud SQL). The postgres driver is what enables replication — durable cross-instance compare-and-set for lifecycle-hook deduplication, versus SQLite's single-instance in-memory approach.
Avoid: clustered hosted, distributed hosted, ha mode, production mode
See also: Single-node hosted, Hosted mode, Tenancy, Proxy Broker, Hosted Broker
Tenancy: Whether a deployment serves a single identity or many — orthogonal to the availability tier. Single-user: one principal, with simple auth (a workstation dev token, or one OAuth identity). Multi-user: many principals authenticated through an OAuth identity provider (Google or GitHub), with Hub Groups and access policies governing who can see and act on what. Local and Workstation modes are single-user by construction; either hosted tier can be single- or multi-user. Avoid: multi-tenancy (for org isolation), single-tenant / multi-tenant (prefer single-/multi-user) See also: Group, Hosted mode, Single-node hosted, HA hosted
Attach: Connecting an interactive terminal to a running agent's tmux session for human-in-the-loop interaction; the agent keeps running once detached. Avoid: connect, join, ssh in
Dispatch: The Hub handing an agent lifecycle command to the appropriate runtime broker for execution. Avoid: schedule, route, assign, delegate
Schedule:
A time-based trigger that fires an action — sending a message or dispatching (starting) an agent from a template — either once (a one-shot scheduled event, via --at <time> or --in <duration>) or repeatedly (a recurring schedule on a 5-field cron expression). Backs scion schedule and the --at/--in flags on scion message.
Avoid: cron job (recurring only), scheduled message (too narrow), reminder, timer
See also: Dispatch
Scion produces two distinct families of metrics. They serve different audiences, use different prefixes, and flow through different pipelines — but both export to the same Cloud Monitoring backend.
Infrastructure metrics:
Operational health metrics for Scion as a system — the Hub process, its database connections, dispatch pipeline, broker authentication, and GCP token minting. These answer "is Scion itself healthy?" and are consumed by platform operators. Prefixes: scion.hub.*, scion.db.*, scion.dispatch.*. Produced by the Hub process; exported directly to Cloud Monitoring via an OTel MeterProvider with a GCP exporter.
Avoid: system metrics, platform metrics, server metrics
See also: Agent metrics (the other family)
Agent metrics:
Telemetry about what agents and their harnesses are doing — token usage, tool calls, model API latency, session counts, and cost signals. These answer "what are the agents doing and what do they cost?" and are consumed by users and project owners. Prefixes: gen_ai.*, agent.* (following OpenTelemetry Generative AI semantic conventions). Produced inside agent containers by the harness and sciontool; exported to Cloud Monitoring via the telemetry pipeline (pkg/sciontool/telemetry).
Avoid: harness metrics, user metrics, LLM metrics
See also: Infrastructure metrics (the other family), Telemetry pipeline
Telemetry pipeline:
The in-container OTLP receiver and forwarding pipeline (pkg/sciontool/telemetry) that collects traces, metrics, and logs from the harness and exports them to a cloud backend (GCP Cloud Monitoring, Cloud Trace, Cloud Logging). Requires the scion-telemetry-gcp-credentials secret for cloud export; runs in local-only mode without it.
Avoid: metrics pipeline, collector, OTel collector
See also: Agent metrics
Session Metrics:
Database-backed summaries and aggregations computed on agent session-end (aggregated by sciontool and delivered as a MetricsPayload in the StatusUpdate protocol) and stored in the Hub's agent_session_metrics SQL table. They provide an IDOR-safe structural view of token usage (input, output, cached, reasoning), tool execution counts, session duration, and model usage, queried via dedicated summary API endpoints and displayed in the Web Dashboard. Contrast with raw OpenTelemetry time-series metrics.
Avoid: OTel metrics (for these DB summaries), raw telemetry
Terms that recur in the codebase and may warrant canonical entries, but are not yet defined here. Listed so they aren't lost; promote to full entries (verified against the code) as the glossary matures.
- Task — the unit tracked by sciontool's task management; referenced operationally but not yet given a canonical definition.
- Capability — a declarative harness feature flag (e.g.
max_turns,session_resume,api_key,stdio) describing what a harness supports. - Resource Spec — per-agent CPU/memory/disk request and limit (Kubernetes-style), applied per agent or via a Profile.
- Label —
scion.*key/value metadata attached to agents and containers for identification and filtering. - Access Policy / scope — the Hub authorization model: allow/deny rules at
hub,project, orresourcescope (the mechanism that grants a Group its access). - Image registry — the container image registry agents pull from (a Profile field).
- Session / tmux session — the per-agent tmux session an Attach connects to.
- Service — a background/sidecar process declared by a Template alongside the agent (currently referenced in the Template entry but undefined).
- Content Hash / Manifest — SHA-based identity for template and harness-config content, used for cache validation and transfer between Hub and runtime brokers.
- Transfer — the signed-URL mechanism that moves templates and harness-configs between the Hub and runtime brokers.
- Service Account — a GCP identity an agent can assume for Google Cloud auth, registered with the Hub.
- Webhook / GitHub App — external event triggers (e.g. GitHub webhooks) that can dispatch agents.
- OAuth provider — a configurable identity provider (Google, GitHub) for CLI and web authentication.