Orchestrator Settings (settings.yaml)
This document describes the configuration for the Scion orchestrator, managed through settings.yaml files. These settings control the behavior of the CLI, local agent execution, and connections to the Scion Hub.
File Locations
Section titled “File Locations”Scion loads settings from the following locations, merging them in order (later sources override earlier ones):
- Global Settings:
~/.scion/settings.yaml(User-wide defaults) - Project Settings:
.scion/settings.yaml(Project-specific overrides) - Environment Variables:
SCION_*overrides.
Versioned Format
Section titled “Versioned Format”Settings files use a versioned format identified by the schema_version field. The current version is 1.
schema_version: "1"active_profile: localdefault_template: geminiTop-Level Fields
Section titled “Top-Level Fields”| Field | Type | Description |
|---|---|---|
schema_version |
string | Required. Must be "1". |
active_profile |
string | The name of the profile to use by default (e.g., local, remote). A new project’s .scion/settings.yaml does not set it, so the project uses the global value; set it in the project file to pin a different profile for that project. In a project linked to a Hub, the project’s Hub settings (scion project settings) decide the defaults (defaultTemplate, activeProfile, defaultHarnessConfig, defaultHarnessAuth, defaultMaxTurns, defaultMaxModelCalls, defaultMaxDuration, defaultResources, defaultGCPIdentity) for agents created through the Hub; the local default_template and active_profile keys apply only as a Runtime Broker fallback when neither the create request nor the Hub provides a value. On a Runtime Broker co-located with a database-backed Hub that stores at least one profile, profiles come from the Hub’s stored profiles; with none stored, the settings file’s profiles apply. The default profile is then active_profile if it is a stored profile. Otherwise, if the Hub stores exactly one profile, that profile is used (the Runtime Broker logs which one and why). Built-in profiles that agents or projects still reference, and the built-in runtimes they need, keep resolving beside the stored profiles (a stored profile of the same name wins). With several stored profiles, a built-in profile that active_profile names is kept as well and used as the default. Otherwise a dispatch that needs the default profile is refused with an error that names the available profiles, listing kept built-ins after retained built-in:. The Hub’s own reads of the default profile follow the same rule. The runtime selector (GET/PUT /api/v1/system/runtime, used during onboarding) does not: it always reads and writes the profile that active_profile names. |
default_template |
string | The default template to use when creating agents (e.g., gemini, antigravity). |
default_harness_config |
string | Default harness config to use. |
default_harness_auth |
string | Default authentication type for new agents (e.g., api-key, vertex-ai, none). |
image_registry |
string | Registry prefix for all standard harness images. Rewrites the registry portion of scion-* images (e.g., ghcr.io/myorg). See Building Custom Images. |
image_tag |
string | Experimental (hub.image_tag_setting). Tag of the standard scion-* images whose tag is latest or absent: version for the Hub binary’s release version (vX.Y.Z, vX.Y.Z-preview.N, or vX.Y.Z-rc.N), or a literal tag (e.g., v0.3.0-preview.5; latest opts out of the version default). A set value is applied only while hub.image_tag_setting is on, but any set image_tag (image_tag: latest included) suppresses hub.image_tag_version_default even while hub.image_tag_setting is off. Unset: a release build (vX.Y.Z, vX.Y.Z-preview.N, or vX.Y.Z-rc.N) of the Hub uses its own version (hub.image_tag_version_default, on by default); other builds and disabled hub.image_tag_version_default leave images unchanged. See Image tag. |
default_max_turns |
int | Default maximum number of turns an agent can take before termination. |
default_max_model_calls |
int | Default maximum number of LLM model calls an agent can make. |
default_max_duration |
string | Default maximum execution time (e.g., "2h", "45m") for an agent. |
default_resources |
object | Default resource requests and limits (requests, limits, disk). See Resource Specification below. |
default_gcp_identity_mode |
string | Hub server only. Hub-wide fallback GCP metadata mode for new agents: block, passthrough, or assign. Applied when neither the create request nor the project’s default GCP identity names one. See Hub-Default GCP Identity. |
default_gcp_identity_service_account_id |
string | Hub server only. ID of the verified, hub-scoped service account assigned when default_gcp_identity_mode is assign. |
CLI Configuration (cli)
Section titled “CLI Configuration (cli)”General behavior settings for the command-line interface.
cli: autohelp: true interactive_disabled: false| Field | Type | Description |
|---|---|---|
autohelp |
bool | Whether to print the usage block after an argument or flag error. Default: true. |
interactive_disabled |
bool | If true, disables all interactive prompts (useful for scripts). |
Hub Client Configuration (hub)
Section titled “Hub Client Configuration (hub)”Settings for connecting the CLI to a Scion Hub.
hub: endpoint: "https://hub.example.com" project_id: "uuid-or-slug"| Field | Type | Description |
|---|---|---|
endpoint |
string | Deprecated and ignored by the CLI, which takes its Hub only from the hub list (Working with Several Hubs); accepted so existing settings files still load, and nothing in the CLI writes it. The value in the global settings is imported once into the hub list as a named hub (local for the workstation hub), and becomes the current hub when none is current; for a linked project, its own value (or the inherited global one) is imported once as that directory’s link entry. To add a hub, use scion hub add <name> <url>. When an agent is provisioned, a hub.endpoint in the agent’s scion-agent.yaml still sets the Hub endpoint that agent is given; when neither it nor the Runtime Broker supplies one, the project’s settings hub.endpoint is used if those settings still mark the Hub as enabled (the deprecated hub.enabled: true, or an endpoint with a token or API key). Servers use server.hub.public_url and server.broker.hub_endpoint instead, and fall back to this value only as a deprecated legacy source (see Server Configuration). |
project_id |
string | The unique identifier for this project on the Hub. |
linked |
bool | Written by the CLI: true once the project is linked, false after scion hub unlink (agent commands then refuse until scion hub link). Unset means never linked; the project links on its first command. |
enabled, local_only |
bool | Deprecated and ignored. Accepted so existing settings files still validate. scion hub status notes it when they are set; see the migration page. |
Runtimes (runtimes)
Section titled “Runtimes (runtimes)”Defines the execution backends available to Scion.
runtimes: docker: type: docker host: "unix:///var/run/docker.sock"
podman: type: podman host: "unix:///run/user/1000/podman/podman.sock"
remote-k8s: type: kubernetes context: "my-cluster" namespace: "scion-agents"| Field | Type | Description |
|---|---|---|
type |
string | The runtime type: docker, podman, container (Apple), kubernetes, or cloudrun (Cloud Run Instances). |
host |
string | (Docker/Podman) The daemon socket or TCP address. Optional for Podman (defaults to CLI). |
context |
string | (Kubernetes) The kubectl context name. |
namespace |
string | (Kubernetes) The target namespace. |
sync |
string | File sync strategy (e.g., tar). |
gke |
bool | (Kubernetes) Enable GKE-specific features (e.g., Workload Identity, Autopilot scheduling). Default: false. |
priority_class_name |
string | (Kubernetes) Default priorityClassName applied to agent pods using this runtime entry. Must name a PriorityClass that already exists on the cluster — Scion does not create one. An agent’s inline config kubernetes.priorityClassName overrides this (a template’s kubernetes block is ignored). Unset means no priority class (pods schedule at priority 0). |
list_all_namespaces |
bool | (Kubernetes) List agents across all namespaces. Default: false. |
shared_dir_storage_class |
string | (Kubernetes) Default StorageClass for shared-dir PVCs. Must support ReadWriteMany. A profile’s value wins over this, and an agent’s inline config kubernetes.shared_dir_storage_class wins over both (a template’s value is ignored). No default: on the local backend, a start that needs a new shared-dir claim fails until a class is set (see Kubernetes: starts that need a new claim). |
shared_dir_size |
string | (Kubernetes) Default size for each shared-dir PVC, as a positive Kubernetes quantity (e.g. 10Gi, 1Ti). Same precedence as shared_dir_storage_class. Default: 10Gi. |
safe_to_evict |
bool | (Kubernetes) Set to false to add the cluster-autoscaler.kubernetes.io/safe-to-evict: "false" annotation to agent pods. Only false has an effect; unset or true adds nothing. A profile’s value wins over this, and an agent’s inline config kubernetes.safeToEvict wins over both (a template’s value is ignored). Ignored, with a validation warning, on other runtime types. |
kubernetes_service_account_mappings |
map | (Kubernetes) Map of lowercase GCP service account email to Kubernetes ServiceAccount name, used by GCP identity mode assign: the agent pod runs as the mapped ServiceAccount through GKE Workload Identity. The ServiceAccount must already exist in this entry’s namespace and be bound to the service account; Scion does not create or bind it. A profile’s entry for the same email wins over this. Without an entry, the broker uses the one ServiceAccount in the namespace annotated iam.gke.io/gcp-service-account with the email, if there is exactly one; that discovery needs list on serviceaccounts in the namespace. Read from global settings only; a project’s settings.yaml value is ignored. See GCP identity mode “assign”. |
kubernetes_block_service_account |
string | (Kubernetes) Kubernetes ServiceAccount the agent pod runs as when its GCP identity mode is block. Use a dedicated ServiceAccount with no Workload Identity annotation and no IAM grants; Scion does not create or check it. Unset or empty: the pod runs as the namespace’s default ServiceAccount. A profile’s value wins over this. Read from global settings only. See block. |
node_selector |
map | (Kubernetes) Operator-owned nodeSelector (map[string]string) applied to agent pods using this runtime entry. All Kubernetes runtime entries targeting the same context and namespace must agree on their placement fields. A profile’s node_selector merges per key over this (except scion.dev/pool, which a profile cannot change). An agent’s kubernetes.nodeSelector may add keys not set by the operator policy, but cannot change any operator-set key. See Flat instance placement. |
tolerations |
list | (Kubernetes) Operator-owned pod tolerations (key, operator, value, effect). A profile’s tolerations merge with this list. Each of an agent’s kubernetes.tolerations must match an operator toleration (and an empty-key Exists toleration on an agent is always refused). |
runtime_class_name |
string | (Kubernetes) Operator-owned runtimeClassName (DNS-1123 subdomain) for agent pods. A profile’s non-empty runtime_class_name wins over this. An agent’s kubernetes.runtimeClassName must be empty or match the resolved operator value. |
cloudrun |
object | (Cloud Run Instances) Settings when type is cloudrun: project_id, location, service_account, network, subnetwork, nfs_server, nfs_export, assignable_service_accounts (global settings only: list of lowercase *.gserviceaccount.com GCP service account emails this Runtime Broker may attach to an instance for GCP identity mode assign while hub.cloudrun_native_identity is on; reported on heartbeats in serviceAccountMappings with source: "cloudrun_allowlist"; empty or unset refuses assign, and a project’s settings.yaml value is ignored with a warning), and block_service_account (global settings only: lowercase *.gserviceaccount.com GCP service account email the instance runs as when the agent’s GCP identity mode is block, unset, or a hub-default passthrough while hub.cloudrun_native_identity is on; reported on heartbeats only as the boolean cloudRunBlockAccount, never by email; unset refuses block with 400, and a project’s settings.yaml value is ignored with a warning). |
env |
map | Environment variables to set for the runtime. |
Storage placement is not a per-runtime or per-profile setting. The former shared_dir_storage_backend, shared_dir_storage_backends, home_storage_backend and home_storage_leaf keys are removed: settings validation, the Hub admin settings API (PUT /api/v1/admin/server-config) and flat Runtime Broker instance loading reject them with an error that names server.project_storage, which places every agent’s workspace, shared directories and home. If an existing settings file or stored runtime/profile still carries one of these keys, startup reports storage_overrides as degraded (storage_override_errors on GET /api/v1/admin/server-config) and starting an agent on that profile or runtime (or an agent whose legacy shared-dir-storage.json pins nfs while the project storage layout is not shared) is refused before anything is created with 422 storage_migration_required. For a node-local directory, such as a build cache, use an ordinary volumes: entry instead.
The cloudrun runtime needs an NFS (Filestore) workspace share: set server.project_storage.backend to nfs with the share in nfs.shares[0]. In clone-per-agent mode on cloudrun, each agent mounts its own workspace directory on the share (<subpath_root>/<project id>/agents/<slug>/workspace, cloned inside the container on first start by sciontool init) instead of the shared <subpath_root>/<project id>/workspace checkout. At every start, the Runtime Broker provisions the Agent home onto <subpath_root>/<project id>/agents/<slug>/home-<agent id> on the share (bounded at 4096 entries, 64 MiB, and 32 directory levels, without following symbolic links), while harness credentials and harness outputs stay on a 16Mi in-memory volume (scion-mem) and the agent’s Hub credential arrives via staged secrets (SCION_HUB_TOKEN_STAGED). A start acts only on its own run’s Cloud Run instance: if an existing instance belongs to another run (scion.run_id), the start refuses with a run conflict (ErrRunConflict) without replacing that instance or touching its directories, and if instance creation is refused before an instance exists, start cleanup removes only the NFS directories (home-<agent id>, workspace, agents/<slug>) that this start created. When the hub.cloudrun_native_identity experiment is on, the Hub checks the broker’s stored profile report (mappingsReportVersion 3, cloudRunNativeIdentity: true, cloudRunBlockAccount, and serviceAccountMappings with source: "cloudrun_allowlist") before dispatch and refuses an unmapped or unsupported identity with 422 identity_not_mapped, records native_cloud_run: true on appliedConfig (cleared only after a confirmed stop or delete), sends the native marker (gcp_identity.native_cloud_run on create, SCION_METADATA_NATIVE_CLOUDRUN=1 in resolved env on start and restart), strips gcp:token:* scopes from the agent’s Hub tokens, and refuses POST /api/v1/agent/gcp-token and POST /api/v1/agent/gcp-id-token with 403 forbidden. On the Runtime Broker, GCP identity mode assign runs the instance as the Hub-assigned service account (requiring the Hub’s native marker and an entry in global cloudrun.assignable_service_accounts, and refusing when SCION_INIT_FIREWALL is enabled or invalid) with SCION_METADATA_MODE=passthrough inside the container, while block, an unset mode, or a hub-default passthrough runs the instance as global cloudrun.block_service_account with SCION_METADATA_MODE=block inside the container (400 if block_service_account is unset), explicit or project-default passthrough is refused with 400, and this run’s existing instance is deleted and recreated on start or restart rather than started in place (see Hub-Default GCP Identity). Each IAP SSH exec (IAPExecConnector) looks up the target instance via the Cloud Run Instances API and names its service_account in the OS Login signSshPublicKey request, fails (dropping any cached key) when the instance’s service account cannot be determined, reuses a signed key only for the same instance (name and UID) and service account while at least 60 seconds of validity remain, and drops the cached key on Stop, Delete, and launch cleanup (DeleteResource). scion doctor checks iam.serviceAccounts.actAs on cloudrun.service_account (roles/iam.serviceAccountUser is required even when it is the Hub’s own service account) and warns when project_storage.homes is set on the Cloud Run profile. Agent start on cloudrun with any other workspace backend is refused before an instance is created.
Harness Configs (harness_configs)
Section titled “Harness Configs (harness_configs)”Named configurations for agent harnesses. This replaces the legacy harnesses map.
harness_configs: gemini: harness: gemini-cli image: "us-central1-docker.pkg.dev/.../scion-gemini-cli:latest" user: scion model: "gemini-1.5-pro"
claude-beta: harness: claude image: "custom-claude:beta" env: ANTHROPIC_BETA: "true"| Field | Type | Description |
|---|---|---|
harness |
string | Required. The harness type (e.g., gemini-cli, claude, opencode). |
image |
string | Container image to use. |
user |
string | Unix username inside the container. |
model |
string | Default model identifier. |
task_flag |
string | CLI flag name for passing the task (e.g., --input). When set, the task is delivered as a flag value instead of a positional argument. |
args |
list | Additional CLI arguments for the harness. |
env |
map | Environment variables injected into the container. |
volumes |
list | Volume mounts. |
auth_selected_type |
string | Authentication method selection (harness-specific). |
secrets |
list | Required secrets for this harness configuration (see below). |
Resource Specification (resources)
Section titled “Resource Specification (resources)”Defines the compute and disk constraints for an agent’s container. The same shape is used by default_resources, profiles.<name>.resources, profiles.<name>.harness_overrides.<harness-config>.resources, and an agent’s inline-config resources field (a template’s is ignored). Harness configs themselves (harness_configs.<name>) have no resources field.
resources: requests: cpu: "500m" memory: "1Gi" limits: cpu: "2" memory: "8Gi" disk: "40Gi"| Field | Type | Description |
|---|---|---|
requests.cpu |
string | CPU request (for example "500m" or "1"). Kubernetes: CPU request. Cloud Run (cloudrun): used when limits.cpu is unset. |
requests.memory |
string | Memory request (for example "1Gi"). Docker/Podman: --memory-reservation. Kubernetes: memory request. Cloud Run (cloudrun): used when limits.memory is unset. |
limits.cpu |
string | CPU limit. Docker/Podman: --cpus. Kubernetes: CPU limit. Cloud Run (cloudrun): instance CPU ("1", "2", "4", "6", or "8" whole vCPU). |
limits.memory |
string | Memory limit. Docker/Podman: --memory. Kubernetes: memory limit. Cloud Run (cloudrun): instance memory (512Mi to 32768Mi (32Gi) in whole Mi or M, within the vCPU band below). Exceeding it OOM-kills a process in the container. |
disk |
string | Kubernetes only. Sets the pod’s ephemeral-storage request and limit to this value. Ignored by Docker/Podman; not mapped on Cloud Run (cloudrun, logged as disk_not_applied). |
Tiers merge field by field: a field set at a higher tier wins, and fields it leaves empty come from lower tiers. See Settings Precedence.
Defaults.
- All runtimes:
limits.cpu: "2"is applied when no tier sets a CPU limit, unlessruntime.enforce_resource_defaultsisfalse(defaulttrue). There is no default memory limit. - Cloud Run (
cloudrun): each resource usesresources.limits.cpu/resources.limits.memory, falling back toresources.requests.cpu/resources.requests.memorywhen no limit is set (unlessruntime.enforce_resource_defaultsisfalse,limits.cpuis already set to the built-in"2", raised torequests.cpuwhenrequests.cpuis above2), and a resource left unset is checked at its platform default (1vCPU,512Mi). Values are validated before any workspace or home directory is provisioned on the NFS share: CPU must be1,2,4,6or8whole vCPU ("a Cloud Run instance takes 1, 2, 4, 6 or 8 vCPU"), and memory must be a whole number ofMiorM("memory must be a whole number of Mi or M on Cloud Run") from512Mito32768Mi(32Gi) within the vCPU’s allowed memory range (1vCPU:512Mito4096Mi;2vCPU:512Mito8192Mi;4vCPU:2048Mito16384Mi;6vCPU:4096Mito24576Mi;8vCPU:4096Mito32768Mi). A value outside these limits (ResourceLimitsError) answers HTTP400(validation_error) on synchronous create, start, and restart, and ends an asynchronous launch with launch error codecontainer_config.resources.diskis not mapped (logged asdisk_not_appliedwhen set). - Kubernetes only:
cpu,memoryandephemeral-storageeach get a default request (250m,512Miand10Gi) only when neither a request nor a limit is set for that resource, inresourcesor inkubernetes.resources. When a limit is set without a request, the request is left unset and Kubernetes sets it equal to the limit. So with the built-in CPU limit a pod requests and is limited to 2 CPU, and a profile that sets onlylimits.memoryis scheduled at that limit. - Kubernetes never adds a default memory or ephemeral-storage limit. Those limits apply only when you set
limits.memoryordisk(or the same key inkubernetes.resources.limits). Withruntime.enforce_resource_defaults: falseand no resources set, a Kubernetes pod gets the three default requests and no limits. - The built-in CPU limit never ends up below a larger CPU request. If
requests.cpuis above2and no tier setslimits.cpu, the built-in limit is raised to the request, on every runtime. Ifkubernetes.resources.requests.cpuis above the resulting limit andkubernetes.resources.limits.cpuis unset,kubernetes.resources.limits.cpuis set to that request; Docker and Podman keep--cpus 2. A CPU limit you set yourself is never changed, so keep it at or above your CPU request.
Required Secrets
Section titled “Required Secrets”Define secrets that must be provided to the agent. During agent creation, Scion utilizes an interactive secrets-gather pipeline to prompt for missing values if they are not already securely stored on the backend, ensuring sensitive credentials are never written to plain text configuration files.
secrets: - key: GEMINI_API_KEY description: "Gemini API key" type: environment - key: service_account description: "Service account JSON" type: file target: /run/secrets/sa.json| Field | Type | Description |
|---|---|---|
key |
string | Required. The secret key name. |
description |
string | Human-readable description. |
type |
string | Projection type: environment (default), variable, or file. |
target |
string | For file type, the path where the secret is mounted. |
Profiles (profiles)
Section titled “Profiles (profiles)”Profiles bind a Runtime to a set of Harness Configs and overrides. They allow you to switch between environments (e.g., “Local Docker” vs “Remote Kubernetes”) easily.
profiles: local: runtime: docker default_template: gemini default_harness_config: gemini harness_overrides: gemini: image: "gemini:dev"| Field | Type | Description |
|---|---|---|
runtime |
string | Required. Name of a runtime defined in runtimes. |
default_template |
string | Default template for agents created under this profile. |
default_harness_config |
string | Default harness config name for agents created under this profile. |
image_registry |
string | Profile-level registry. Beats the top-level image_registry of the same source; a saved Hub top-level value and a node’s SCION_IMAGE_REGISTRY beat a settings-file profile value. See Image registry order. |
image_tag |
string | Experimental (hub.image_tag_setting). Profile-level image tag (version, latest, or a literal tag). Beats the top-level image_tag of the same source; any set image_tag suppresses the hub.image_tag_version_default release version default even while hub.image_tag_setting is off, and a set value is applied only while hub.image_tag_setting is on. See Image tag. |
volumes |
list | Volume mounts for agents created under this profile, appended after the harness config’s volumes. Each entry has target (required), source, read_only, type, bucket (GCS bucket name), prefix (GCS object prefix), mode (mount options), server (NFS server host or IP) and volume_name (Cloud Run or GKE volume name). type is local (default; host bind mount, requires source), gcs (GCS FUSE mount, requires bucket), nfs (NFS mount, requires server and source), cloudrun-volume (Cloud Run managed volume, requires volume_name) or gke-shared-volume (GKE-provided shared volume such as a Filestore CSI PVC, requires volume_name). |
harness_overrides |
map | Per-harness-config overrides. Keys match harness_configs names. |
secrets |
list | Required secrets for agents created under this profile. |
resources |
object | Resource requests and limits for agents created under this profile. See Resource Specification. |
shared_dir_storage_class |
string | (Kubernetes) StorageClass for shared-dir PVCs created under this profile. Wins over the runtime entry’s value; an agent’s inline config kubernetes.shared_dir_storage_class wins over this (a template’s value is ignored). |
shared_dir_size |
string | (Kubernetes) Size for each shared-dir PVC created under this profile. Same precedence as shared_dir_storage_class. |
safe_to_evict |
bool | (Kubernetes) Safe-to-evict setting for agent pods created under this profile. Wins over the runtime entry’s value; an agent’s inline config kubernetes.safeToEvict wins over this (a template’s value is ignored). |
clone_depth |
string or int | Git clone depth for clone-per-agent workspaces of agents under this profile: full for a full (non-shallow) clone, or an integer N from 1 to 999999999 for a clone of depth N. A template or agent clone_depth wins over this. Unset (absent, null or empty) keeps the default shallow (depth 1) clone. Applies only when the workspace is cloned (a new agent, or a recreated workspace). |
kubernetes_service_account_mappings |
map | (Kubernetes) Per-profile override of the runtime entry’s kubernetes_service_account_mappings: for each service account email listed here, this ServiceAccount name wins over the runtime entry’s. Other emails fall through to the runtime entry. Read from global settings only. |
kubernetes_block_service_account |
string | (Kubernetes) Per-profile override of the runtime entry’s kubernetes_block_service_account. Read from global settings only. |
node_selector |
map | (Kubernetes) Operator-owned nodeSelector (map[string]string) layered over the runtime entry’s node_selector per key (a profile may repeat scion.dev/pool with the same value or omit it, but cannot change it). Set at the profile level, not under resources. See Flat instance placement. |
tolerations |
list | (Kubernetes) Operator-owned pod tolerations merged with the runtime entry’s tolerations by exact tuple (key, operator with empty normalized to Equal, value, effect). Set at the profile level, not under resources. |
runtime_class_name |
string | (Kubernetes) Operator-owned runtimeClassName (DNS-1123 subdomain) that wins over the runtime entry’s runtime_class_name when non-empty. Set at the profile level, not under resources. |
A profile cannot choose where its agents’ storage lives: the removed shared_dir_storage_backend, shared_dir_storage_backends, home_storage_backend and home_storage_leaf keys are rejected by validation, reported as storage_overrides at startup, and refused at agent start with 422 storage_migration_required (see the note under the runtime entry table above). Use volumes for a node-local directory.
Shared-dir PVC class and size (Kubernetes). Each key is resolved separately, and the first source that sets it wins: the agent’s inline config kubernetes: block (a template’s is ignored), then the profile, then the profile’s runtime entry, then the built-in default (the cluster’s default class and 10Gi). On GKE Autopilot, set an RWX class such as standard-rwx. See Shared Directory PVCs.
Safe-to-evict (Kubernetes). The first source that sets safe_to_evict wins: the agent’s inline config kubernetes.safeToEvict (a template’s is ignored), then the agent’s profile (--profile, or the profile the agent was created with, falling back to the active profile), then that profile’s runtime entry. An explicit true at a higher level turns the annotation off even when a lower level sets false. On GKE Autopilot the annotation makes the pod an extended run time pod, which has its own limits and cost. See Safe-to-Evict.
Clone depth. The first source that sets clone_depth wins: the agent’s or template’s clone_depth, then the agent’s profile (--profile, or the profile the agent was created with, falling back to the active profile). When neither sets it, a clone-per-agent workspace is a shallow clone of depth 1. full clones the whole history, so git rev-parse --is-shallow-repository prints false and rebase, merge-base, git log and blame work without git fetch --unshallow. 0, values above 999999999 and other values are rejected; use full for a full clone. The setting applies only when the broker clones the repository per agent (clone-per-agent); on the Kubernetes runtime it reaches both the NFS provisioning init container and the in-container clone, and on the Cloud Run (cloudrun) runtime it reaches the in-container clone. It takes effect only when the workspace is cloned: a new agent, or an agent whose workspace is recreated. Restarting an agent whose workspace is already a shallow clone keeps it shallow; to deepen it in place, run git fetch --unshallow in the workspace. For example:
profiles: gke: runtime: gke-autopilot clone_depth: fullAgent timezone. Profiles do not set the TZ of a Hub-dispatched agent: a TZ in a profile’s harness_overrides env is not used (profiles have no env key). The Hub-level default is agent_defaults.default_timezone (in settings.yaml, the top-level default_timezone key). For the full order and pins, see Times and Timezones.
Removed: profile timezone
Section titled “Removed: profile timezone”The profile timezone field was removed. A request to PUT /api/v1/admin/server-config that still sends profiles.<name>.timezone, even as an empty string, is rejected with 422. At startup a Postgres-backed Hub strips stored values from its profile settings. If exactly one zone was set and no Hub default existed, it is copied into agent_defaults.default_timezone, and agent_defaults then becomes admin-managed, so settings.yaml no longer seeds it on that Hub. A file-based Hub never rewrites settings.yaml; it logs each leftover key, and the default_timezone: <zone> line to add when one zone would have been copied.
Volume Source Restrictions
Section titled “Volume Source Restrictions”A Runtime Broker refuses any agent mount whose host source reaches the Runtime Broker host’s own control files. This applies to every volumes: entry, whatever sets it (settings, profiles, harness configs, templates, flat Runtime Broker instance agent_defaults, or a create or start request from the Hub). It applies equally to read-only and read-write mounts. It also applies to shared directories, workspaces, agent homes and harness auth files.
The protected paths are, in the Scion global directory (~/.scion):
| Class | Paths |
|---|---|
| Credentials | broker-credentials.json, hub-credentials/, dev-token, hub-profiles/, transport-token, scion-token |
| Local settings | settings.yaml, settings.yml, settings.json, .settings.lock, server.yaml |
| Host identity and state | runtime-brokers/, runtime-broker-state/, broker-workspaces/, hub-workspaces/, workspace-config-records/, server.pid, .scion (the global project marker) |
| Host plugins | plugins/ |
| Hub state | hub-id, and hub.db with its -wal, -shm and -journal files |
The Runtime Broker’s configured state directory (server.broker.state_dir) and a co-located Hub’s SQLite database file are protected wherever they are configured.
A mount source is refused when:
-
it equals one of these paths, contains one, or lies inside a protected directory;
-
it is the Scion global directory itself, or contains it (for example
~or/); -
it lies inside the Scion global directory but outside the agent-data subtrees below. For
volumes:and shared directories, only these are allowed:~/.scion/workspace/...~/.scion/projects/<project>/workspace/...~/.scion/projects/<project>/worktrees/<name>/...~/.scion/projects/<project>/.scion/agents/<agent>/workspace/...~/.scion/project-configs/<dir>/.scion/agents/<agent>/workspace/...~/.scion/project-configs/<dir>/shared-dirs/<name>/...
Harness auth files and
SCION_DEV_BINARIESmay not come from the Scion global directory at all. -
it cannot be resolved: a relative path (other than a named volume), a dangling symbolic link, or a path the Runtime Broker cannot read.
Symbolic links are resolved on both sides before the comparison, and the resolved path is what gets mounted. The error a requester sees has the code control_path_mount. It names the source as configured and the class of path it reaches, never the resolved host path. The Runtime Broker log adds the resolved paths.
The check runs at each of these points:
- Runtime Broker start. The Runtime Broker does not start when its worktree base or its NFS mount root (
nfs.mount_rootof the workspace storage settings) equals or contains a protected path. A flat Runtime Broker host does not start when an instance’sagent_defaultsor harness override volumes reach one. - Agent create and start. A Hub request whose volumes reach a protected path is refused with
400, before anything is saved. The agent’s merged volumes are checked again before its configuration is written. - Container creation. Every bind is checked just before the container is created, and the Runtime Broker records the binds it requested on the container (the
scion.bind_sourceslabel). Right after creation, the binds the runtime reports must match that record exactly and are checked again. A refused or mismatching bind stops the container and fails the start. - Running agents. The Runtime Broker re-checks the binds of running agents on its default runtime and on every non-default Docker, Podman or Apple container runtime it has registered. At startup it registers the runtime profiles of Hub-managed projects, of shared-storage projects that have agents on this Runtime Broker, and of the project it was started from. It registers other projects’ runtime profiles once it has used them since it started. It does this at startup, every 60 seconds, and sooner when the protected paths resolve somewhere else. An agent with a refused or mismatching bind is stopped and marked
error. An agent whose mounts cannot be verified twice in a row is stopped too. A Docker or Podman agent created before this check existed has no bind record. It keeps running only if its container runtime is reached over a local unix socket and every bind source the runtime reports exists on the host and passes the check. Otherwise it is stopped and must be started again. That covers a remote daemon, whether selected withDOCKER_HOST, a Docker context,CONTAINER_HOSTor a Podman connection, and a locality that cannot be determined. Apple container agents created before this check existed are always stopped once. If a protected path cannot be resolved at all (for example a dangling symbolic link at~/.scion/settings.yaml), nothing can be verified, so every running agent on the host is stopped until it is fixed.
Limitations.
- Remote Docker daemon. These checks protect a Runtime Broker whose container runtime runs on the same host. With a remote Docker daemon (
DOCKER_HOSTpointing at another machine), bind sources name paths on the daemon’s host, which the Runtime Broker cannot verify. The operator must keep the Runtime Broker’s control files off that host and out of every bind source. - Apple container runtime. The re-checks after creation and for running agents read only the binds the Runtime Broker recorded on the container when it created it, not the runtime’s own view of what it mounted.
- Non-default runtimes of other projects after a restart. Take an agent created before this check existed, on a non-default runtime (for example Podman on a Runtime Broker whose default is Docker), in a linked project the Runtime Broker has not used since it started. That agent is not re-checked until the Runtime Broker uses its project again. Every new agent is still checked when it is created.
- Agents created before this check existed. For these agents only, the re-check trusts the bind sources the runtime reports, since there is no record to compare them with. A Docker Desktop path of the form
/host_mnt/<host path>is judged as<host path>. Locality is judged by the daemon endpoint alone. A local unix socket that forwards to a daemon on another host or filesystem (for example an SSH-forwarded socket) is therefore treated as local. - Runtime listing. If the Runtime Broker cannot list a runtime’s containers, it cannot tell which agents to check, so it stops none and tries again at the next check.
- Hard links. Directories are not walked. A hard link to a protected file, placed inside an allowed directory by a process on the host, is not detected. An agent cannot create such a link itself.
Telemetry Configuration (telemetry)
Section titled “Telemetry Configuration (telemetry)”Controls agent telemetry collection, forwarding, privacy filtering, and debug output. Telemetry settings can be defined at global or project scope and are merged across the hierarchy (last write wins). A template’s telemetry block is ignored; the Hub telemetry configuration and project telemetry policy also apply, and an agent’s own config can only turn telemetry on or off. See the telemetry ladder.
See the Metrics & OpenTelemetry guide for operational details.
Basic Example
Section titled “Basic Example”telemetry: enabled: true cloud: enabled: true endpoint: "monitoring.googleapis.com:443" protocol: grpc filter: events: exclude: - "agent.user.prompt"Cloud Forwarding (telemetry.cloud)
Section titled “Cloud Forwarding (telemetry.cloud)”Settings for forwarding telemetry to a cloud OTLP backend.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | true |
Enable cloud forwarding. |
endpoint |
string | — | Cloud OTLP endpoint URL. |
protocol |
string | grpc |
Transport protocol: grpc or http. |
provider |
string | — | Cloud provider name (for example gcp). |
cloud_logging |
bool | false |
Send the Scion server’s (Hub’s) own logs directly to Google Cloud Logging. Read once at server startup; SCION_CLOUD_LOGGING, when set (even to false), takes precedence over the file. Agents do not use it: the value is carried into the agent’s resolved telemetry config (telemetry.cloud.cloud_logging) but is not passed to the agent as an environment variable. On a database-backed Hub it cannot be changed through PUT /api/v1/admin/server-config (422 startup_only_key_rejected). |
headers |
map | — | Additional headers for OTLP export (e.g., Authorization). |
tls.enabled |
bool | true |
Enable TLS for the connection. |
tls.insecure_skip_verify |
bool | false |
Skip TLS certificate verification (development only). |
batch.max_size |
int | 512 |
Maximum spans per batch export. |
batch.timeout |
string | 5s |
Maximum wait time before flushing a partial batch. |
Hub Reporting (telemetry.hub)
Section titled “Hub Reporting (telemetry.hub)”Settings for reporting telemetry summaries to the Scion Hub.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | true |
Enable Hub telemetry reporting. Auto-enabled in hosted mode. |
report_interval |
string | 30s |
Interval between Hub reports. |
Local Debug Output (telemetry.local)
Section titled “Local Debug Output (telemetry.local)”Settings for local debug telemetry output. These keys are accepted so existing settings files still load, but no component reads them today, so they have no effect.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | false |
Accepted but ignored. |
file |
string | — | Accepted but ignored. |
console |
bool | false |
Accepted but ignored. |
Filtering (telemetry.filter)
Section titled “Filtering (telemetry.filter)”Controls event filtering, attribute redaction, and sampling.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool | true |
Enable event filtering. |
respect_debug_mode |
bool | true |
Accepted but ignored: no component reads this key today. |
events.include |
list | [] |
Event types to include (empty = all). |
events.exclude |
list | ["agent.user.prompt"] |
Event types to exclude. |
attributes.redact |
list | See below | Attribute names to replace with [REDACTED]. |
attributes.hash |
list | ["session_id"] |
Attribute names to SHA256 hash. |
sampling.default |
float | 1.0 |
Default sampling rate (0.0–1.0). |
sampling.rates |
map | {} |
Per-event-type sampling rate overrides. |
Default redacted attributes: prompt, user.email, tool_output, tool_input.
Resource Attributes (telemetry.resource)
Section titled “Resource Attributes (telemetry.resource)”Static key-value pairs added to all telemetry events. Useful for tagging deployments.
telemetry: resource: service.name: "scion-agent" deployment.env: "staging"Server Configuration (server)
Section titled “Server Configuration (server)”When running the scion server (Hub or Broker), configuration is read from the server section of settings.yaml.
See the Server Configuration Reference for details.
Environment Variable Overrides
Section titled “Environment Variable Overrides”Settings can be overridden using environment variables with the SCION_ prefix.
| Setting | Environment Variable |
|---|---|
active_profile |
SCION_ACTIVE_PROFILE |
default_template |
SCION_DEFAULT_TEMPLATE |
hub.project_id |
SCION_HUB_PROJECT_ID |
cli.autohelp |
SCION_CLI_AUTOHELP |
telemetry.enabled |
SCION_TELEMETRY_ENABLED |
telemetry.cloud.enabled |
SCION_TELEMETRY_CLOUD_ENABLED |
telemetry.cloud.cloud_logging (server process only) |
SCION_CLOUD_LOGGING |
telemetry.cloud.endpoint |
SCION_OTEL_ENDPOINT |
telemetry.cloud.protocol |
SCION_OTEL_PROTOCOL |
telemetry.cloud.tls.enabled (inverted) |
SCION_OTEL_INSECURE |
telemetry.cloud.tls.insecure_skip_verify |
SCION_OTEL_SKIP_TLS_VERIFY |
telemetry.cloud.tls.ca_file |
SCION_OTEL_CA_FILE |
telemetry.cloud.tls.cert_file |
SCION_OTEL_CERT_FILE |
telemetry.cloud.tls.key_file |
SCION_OTEL_KEY_FILE |
telemetry.hub.enabled |
SCION_TELEMETRY_HUB_ENABLED |
See Local Governance for more on variable substitution.