Skip to content

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.

  • Templates: .scion/templates/<template-name>/scion-agent.yaml
  • Active Agents: .scion/agents/<agent-name>/scion-agent.yaml
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.

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.

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 .md files can gate experimental guidance on a registered experiment in two ways: setting experiment: <id> in YAML frontmatter (which omits the entire skill directory when on SKILL.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, or local_experiments from settings in solo CLI mode, failing closed (any experiment not explicitly enabled is omitted, for example scion-artifacts gated on hub.artifacts and the Choices reference in scion-messaging gated on web.decisions).

These platform skills are managed by Scion and do not need to be manually included in your template definition.

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).

env:
REVIEW_STRICTNESS: high
LINT_CONFIG: /home/scion/.config/lint.yaml

In 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_env any_of keys, required_files alternative_env_keys and autodetect env 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.

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)
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.
resources:
requests:
cpu: "500m"
memory: "512Mi"
limits:
cpu: "2"
memory: "2Gi"
disk: "10Gi"

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.
Field Type Description
type string tcp, http, or delay.
target string Host:port (tcp/http) or duration (delay).
timeout string Maximum wait time.

Inline config only. Specify a different Hub endpoint for this agent.

hub:
endpoint: "https://hub.example.com"

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.

Harness-specific settings for Gemini.

gemini:
auth_selectedType: "vertex-ai"

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: false

Everything 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.

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: false

priorityClassName 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.

When an agent starts:

  1. Template Load: Scion loads scion-agent.yaml from the selected template chain and drops its environment keys and its env (with a warning for environment keys).
  2. Harness Resolution: It resolves the harness_config against the active profile’s harness_configs map in settings.yaml.
  3. Overrides: the project defaults, the inline config and CLI flags (e.g., --model, --image) override the template’s job keys.
  4. 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.

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:

  1. The agent-create request — the value passed to scion agent create, the API, or the web form.
  2. The project setting — the project default.
  3. 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.