Agent Configuration (scion-agent.yaml)
The scion-agent.yaml file describes an agent’s job: what it does, which harness config and model it prefers, its instructions, skills, tools and limits. The same file format is used for templates and for an agent’s own inline config (--config, the create API, the web form), but the two may set different keys. A template describes the job, not the environment: where and how the agent runs (image, resources, volumes, Kubernetes settings, telemetry, hub access) comes from the harness-config, settings and profiles, the hub and the project.
File Locations
Section titled “File Locations”- Templates:
.scion/templates/<template-name>/scion-agent.yaml - Active Agents:
.scion/agents/<agent-name>/scion-agent.yaml
Key classes
Section titled “Key classes”| Class | Keys | In a template | In an inline config | Where the value comes from otherwise |
|---|---|---|---|---|
| Job keys | harness_config / default_harness_config, model, thinking_level, agent_instructions, system_prompt, skills, mcp_servers, command_args, task_flag, max_turns, max_model_calls, max_duration, services, secrets (names only), message_mode |
Set | Set; beats the project and the template | Project defaults, hub agent_defaults, broker settings, the harness-config |
| Template env | env |
A fallback for the job’s own tools | Request env, at its usual System A rank | Settings, hub env scopes, secrets, the runtime |
| Environment keys | image, resources, volumes, kubernetes, hub, telemetry, persistence |
Ignored, with a warning | Set for this agent (telemetry: on/off only; persistence: create only) |
The harness-config (config.yaml), broker settings and profiles, hub settings, project policy |
A template that sets an environment key still loads. The agent start prints template <name> sets environment key(s) <keys>; ignored (environment comes from settings), the hub logs a warning naming the keys when the template is committed, and a hub admin can list every affected template with GET /api/v1/admin/validate-resources (templateConfigFindings, kind environment_keys). Remove the key from the template and set the value where the last column says. For the full precedence of every class, see Settings Precedence.
Edits to a template’s env take effect on an agent’s next start. Its job keys are read when the agent is created.
Configuration Fields
Section titled “Configuration Fields”Core Fields
Section titled “Core Fields”| Field | Type | Description |
|---|---|---|
schema_version |
string | Should be "1". |
default_harness_config |
string | The name of the default harness config to use (e.g., gemini, antigravity). |
agent_instructions |
string | Role-specific instructions for the agent (harness-agnostic). A value with a line break is inline text. A single-line value must be a relative path inside the template directory (an absolute path, .. component, or . is refused); if a template in the chain has that path, it is read as a plain regular file of at most 4 MiB without following symlinks or hard links (an invalid or unreadable file is refused), and if no template in the chain has the file, the value is used as inline text (see scion-agent.yaml). |
system_prompt |
string | The system prompt to use for the agent (harness-agnostic). Follows the same relative template file or inline text rules as agent_instructions. |
harness_config |
string | The harness config to use. When a template sets both this and default_harness_config, default_harness_config wins. |
env |
map | Environment variables. In a template, a lowest-precedence fallback; see Environment variables. |
detached |
bool | Run in background (default true). |
command_args |
list | Additional arguments passed to the harness entrypoint. |
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. |
model |
string | LLM model identifier override. |
thinking_level |
int | Harness-agnostic thinking level from 0 to 100, mapped by the harness-config to a native tier (see Thinking Level Map). |
message_mode |
string | Hub only: the initial message mode (none, lineage, branch, project, hub) for agents created from this template when the create request names none. |
Platform and Workspace Skills
Section titled “Platform and Workspace Skills”Scion automatically injects contextual platform skills into the agent’s environment during provisioning:
git-sandbox: Injected if the agent is running in a Git-backed workspace. Provides operational context for git worktree and branch management.- Platform Skills: Core instructions (such as status signaling, messaging, and command operations) are dynamically injected to guide the agent in interacting with the system.
- Experiment gating: Platform skills and their supporting
.mdfiles can gate experimental guidance on a registered experiment in two ways: settingexperiment: <id>in YAML frontmatter (which omits the entire skill directory when onSKILL.md, or omits that supporting file), or wrapping a section in<!-- scion:experiment <id> -->…<!-- scion:end-experiment -->HTML comments (outside fenced code blocks). At provisioning and start, Scion evaluates these gates against the experiments dispatched by the Hub (HubAgentDefaults.Experiments) in Runtime Broker mode, orlocal_experimentsfrom settings in solo CLI mode, failing closed (any experiment not explicitly enabled is omitted, for examplescion-artifactsgated onhub.artifactsand the Choices reference inscion-messaginggated onweb.decisions).
These platform skills are managed by Scion and do not need to be manually included in your template definition.
Limits
Section titled “Limits”| Field | Type | Description |
|---|---|---|
max_turns |
int | Maximum number of LLM turns before the agent stops. Exceeding this triggers a LIMITS_EXCEEDED state and termination. 0 means no limit and overrides any inherited or default limit; leave the key out to inherit. |
max_model_calls |
int | Maximum number of model calls before the agent stops. 0 means no limit and overrides any inherited or default limit; leave the key out to inherit. |
max_duration |
string | Maximum runtime duration (e.g., "2h", "30m"). Exceeding this triggers a LIMITS_EXCEEDED state and termination. "0" means no limit; leave the key out to inherit. |
Each limit has three states: left out (or null), which inherits the value from the template chain and then from the hub and broker default limits; an explicit “no limit” (0 for a count, "0" for a duration), which overrides an inherited limit and is never filled by a default; and a limit. A negative count is invalid. Before count limits were typed, a max_turns: 0 or max_model_calls: 0 in a template or config file was accepted silently and meant “inherit”; it now means no limit, so remove the key to inherit. A Runtime Broker logs each template that sets a count limit to 0 when it provisions an agent. An explicit count limit of 0 takes effect only on a Runtime Broker that advertises the unlimitedCountLimits capability: at create or start an older broker keeps the inherited limit and the Hub warns about it, while a configuration edit (PATCH /api/v1/agents/:id or PATCH /api/v1/projects/:id/agents/:agentId) that changes max_turns or max_model_calls to 0 is refused with 422 validation_error (unlimited_not_supported_by_broker, or broker_unknown when the agent’s Runtime Broker is not registered).
Environment variables (env)
Section titled “Environment variables (env)”env: REVIEW_STRICTNESS: high LINT_CONFIG: /home/scion/.config/lint.yamlIn a template, env: is for the job’s own tools, and each variable is a fallback:
- It applies only when no other source sets the key. Settings harness-config env, hub, project and user env, request env, secrets, and the env the runtime adds itself (auth, harness and telemetry env) all win over it.
- Values are literal.
${VAR}is not expanded (it is used as written, with a warning), and an empty value is not filled from the broker host’s environment (it is skipped, with a warning). SCION_*keys are ignored. That namespace belongs to the platform.- Credentials never come from a template. Every env key the harness-config’s auth metadata lists (its
required_envany_ofkeys,required_filesalternative_env_keysandautodetectenv keys, for any auth type) is never filled from template env, even when nothing else sets it. Supply credentials as secrets or hub env instead. - Edits take effect on the next start. Template env is not stored in the agent’s config; the broker reads it from the template’s current version on every start. If the template can no longer be found, the start warns and applies none.
In an agent’s inline config, env is request env and ranks above the hub storage scopes; see Settings Precedence.
Environment keys (inline config only)
Section titled “Environment keys (inline config only)”The keys in this section are ignored in templates, with a warning. They take effect only in an agent’s own inline config (--config, the create API or the web form), where they apply to that one agent. Otherwise their values come from the harness-config, settings and profiles, and the hub.
| Field | Type | Description | Set it instead in |
|---|---|---|---|
image |
string | Container image for this agent. | The harness-config’s config.yaml image; settings harness_configs.<name>.image; a profile harness_overrides.<name>.image; --image |
volumes |
list | Additional volume mounts. Subject to Volume Source Restrictions. | Settings harness_configs.<name>.volumes; the harness-config |
resources |
object | Container resource requests/limits (see below). | Settings default_resources, profile resources and harness_overrides; hub agent_defaults.resources; project resource defaults |
kubernetes |
object | Kubernetes runtime overrides (see below). | Settings runtimes and profiles |
hub |
object | Hub endpoint override (see below). | Broker settings |
telemetry |
object | Telemetry. Only enabled is honoured. |
Settings telemetry; hub telemetry config; project telemetry policy |
persistence |
string | Experimental (hub.cloudrun_ephemeral_agents). "persistent" (default when omitted or empty) or "ephemeral". Fixed at creation (TX); an "ephemeral" agent runs on a Cloud Run Runtime Broker that advertises ephemeralPersistence and receives a fresh memory-backed Agent home and workspace on every start, keeping nothing across stops. |
Agent creation request only (POST /api/v1/agents) |
Workspace Clone
Section titled “Workspace Clone”| Field | Type | Description |
|---|---|---|
clone_depth |
string or int | Git clone depth for a clone-per-agent workspace: full for a full (non-shallow) clone, or an integer N from 1 to 999999999 for a clone of depth N. Overrides the profile’s clone_depth. Unset (absent, null or empty) keeps the profile’s value, else the default shallow clone of depth 1. Applies only when the workspace is cloned (a new agent, or a recreated workspace); restarting an agent whose workspace is already a shallow clone keeps it shallow. See Profiles. |
Resource Specification
Section titled “Resource Specification”resources: requests: cpu: "500m" memory: "512Mi" limits: cpu: "2" memory: "2Gi" disk: "10Gi"Sidecar Services (services)
Section titled “Sidecar Services (services)”Define auxiliary containers to run alongside the agent (e.g., a headless browser).
services: - name: browser command: ["chromium", "--headless"] env: DISPLAY: ":99" ready_check: type: tcp target: "localhost:9222" - name: delayed-job command: ["./worker.sh"] ready_check: type: delay target: "5s"| Field | Type | Description |
|---|---|---|
name |
string | Required. Service name. |
command |
list | Required. Entrypoint and arguments. |
restart |
string | Restart policy: no, always, or on-failure. |
env |
map | Environment variables for the service. |
ready_check |
object | Health check to determine if the service is ready. |
Ready Check (ready_check)
Section titled “Ready Check (ready_check)”| Field | Type | Description |
|---|---|---|
type |
string | tcp, http, or delay. |
target |
string | Host:port (tcp/http) or duration (delay). |
timeout |
string | Maximum wait time. |
Hub Override (hub)
Section titled “Hub Override (hub)”Inline config only. Specify a different Hub endpoint for this agent.
hub: endpoint: "https://hub.example.com"Required Secrets (secrets)
Section titled “Required Secrets (secrets)”Declare the secrets the agent’s job needs. A template names secrets only; their values always come from the environment (user, project, hub or broker secrets). These follow the same schema as Orchestrator Settings Secrets.
Gemini Settings (gemini)
Section titled “Gemini Settings (gemini)”Harness-specific settings for Gemini.
gemini: auth_selectedType: "vertex-ai"Telemetry (telemetry)
Section titled “Telemetry (telemetry)”An environment key. A template’s telemetry: block is ignored. Only enabled in the inline config is honoured: it turns telemetry on or off for that agent (the CLI’s --enable-telemetry / --disable-telemetry), below the project’s telemetry policy, and other inline telemetry fields are ignored with a warning.
telemetry: enabled: falseEverything else about telemetry (exporters, filters, resource attributes) is configured in settings and the hub telemetry config. See the Orchestrator Settings Reference for the fields and the telemetry ladder for precedence.
Kubernetes Specifics (kubernetes)
Section titled “Kubernetes Specifics (kubernetes)”Inline config only; ignored in templates. Overrides for Kubernetes runtimes.
kubernetes: namespace: "custom-ns" serviceAccountName: "workload-identity-sa" runtimeClassName: "gvisor" priorityClassName: "scion-agent-priority" safeToEvict: falsepriorityClassName must name a PriorityClass that already exists on the cluster — Scion does not create one — and overrides any runtimes.<name>.priority_class_name default set in settings.yaml. See Running Scion on Kubernetes for why to set it.
safeToEvict: false adds the cluster-autoscaler.kubernetes.io/safe-to-evict: "false" annotation to the pod. It overrides safe_to_evict on the profile and the runtime entry, and an explicit true turns the annotation off. See Safe-to-Evict.
Resolution Logic
Section titled “Resolution Logic”When an agent starts:
- Template Load: Scion loads
scion-agent.yamlfrom the selected template chain and drops its environment keys and itsenv(with a warning for environment keys). - Harness Resolution: It resolves the
harness_configagainst the active profile’sharness_configsmap insettings.yaml. - Overrides: the project defaults, the inline config and CLI flags (e.g.,
--model,--image) override the template’s job keys. - Final Config: The resolved job config and the requester’s own environment values are written to the agent’s runtime directory. Image, resources, volumes and telemetry from settings, profiles and the hub are applied at each start and are not written there. Template env is applied at each start as a fallback.
Project settings precedence
Section titled “Project settings precedence”Agents created inside a hub project have one more source of values: the
project’s own defaults, set in Project Settings (or with scion project settings) and stored as scion.io/*
annotations on the project. For these fields the ordering is, highest priority
first:
- The agent-create request — the value passed to
scion agent create, the API, or the web form. - The project setting — the project default.
- The template — the value in the selected template’s
scion-agent.yaml.
| Field | Project setting |
|---|---|
harness_config |
scion.io/default-harness-config |
model |
scion.io/default-model |
| Active profile | scion.io/active-profile |
max_turns |
scion.io/default-max-turns |
max_model_calls |
scion.io/default-max-model-calls |
max_duration |
scion.io/default-max-duration |
resources |
scion.io/default-resources-cpu-request, -memory-request, -cpu-limit, -memory-limit, -disk |
A project setting is an override: it takes precedence over the template the
project uses. Leave it blank (null in PUT /api/v1/projects/:id/settings) to let the template — and then the rest of the
chain — decide. Blank means unset, falls through — it does not mean “set to
whatever the default happens to be”. For the two project count limits (defaultMaxTurns / scion.io/default-max-turns and defaultMaxModelCalls / scion.io/default-max-model-calls), 0 is Unlimited — an explicit “no limit” that new agents receive in their inline config, overriding any template, Hub, or Runtime Broker default limit — while null clears the project setting back to inheriting and a negative value is refused with 422 validation_error (the Project Settings and Agent Configuration forms in the Web UI provide a Limited / Unlimited selector for both fields). Changing a project default count limit to 0 records a project_settings_limit_unlimited mutation audit event (and logs a warning when the field was previously unset, since a browser tab opened before the upgrade sends 0 for an empty field) and returns a warnings entry when a Runtime Broker providing the project does not advertise unlimitedCountLimits (agents on such a broker keep the inherited limit).
resources merges field by field rather than as a whole block. An inline
config that sets only a memory limit keeps that limit and still picks up the
project’s CPU and disk defaults. The three limit fields are filled field by field
in the same way.
Values resolved above are stamped onto the agent by the hub before dispatch, so
they outrank anything the broker would otherwise supply from its local
settings.yaml. That is intended: hub configuration should win for a
hub-created agent. Hub agent_defaults are the exception: they fill only what the
request, the project and the template all left unset.