Agent Configuration (scion-agent.yaml)

The scion-agent.yaml file acts as the blueprint for an agent. It defines the environment, resources, and harness configuration required to run the agent.

File Locations

Templates: .scion/templates/<template-name>/scion-agent.yaml
Active Agents: .scion/agents/<agent-name>/scion-agent.yaml

Configuration Fields

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`, `claude`).
`agent_instructions`	string	Role-specific instructions for the agent (harness-agnostic).
`system_prompt`	string	The system prompt to use for the agent (harness-agnostic).
`image`	string	Override the container image defined in the harness config.
`env`	map	Environment variables to inject into the container.
`volumes`	list	Additional volume mounts.
`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.

Automatic Instruction Extensions

Scion automatically appends contextual instructions to the base agent_instructions during provisioning:

agents-git.md: Appended if the agent is running in a Git-backed workspace. Provides operational context for git worktree and branch management.
agents-hub.md: Appended if the agent is connected to a Scion Hub. Provides instructions for status reporting and Hub API interaction.

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

Limits & Resources

Field	Type	Description
`max_turns`	int	Maximum number of LLM turns before the agent stops. Exceeding this triggers a `LIMITS_EXCEEDED` state and termination.
`max_duration`	string	Maximum runtime duration (e.g., `"2h"`, `"30m"`). Exceeding this triggers a `LIMITS_EXCEEDED` state and termination.
`resources`	object	Container resource requests/limits (see below).

Resource Specification

resources:
  requests:
    cpu: "500m"
    memory: "512Mi"
  limits:
    cpu: "2"
    memory: "2Gi"
  disk: "10Gi"

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

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

Specify a different Hub endpoint for this agent.

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

Required Secrets (`secrets`)

Define secrets required by the agent. These follow the same schema as Orchestrator Settings Secrets.

Gemini Settings (`gemini`)

Harness-specific settings for Gemini.

gemini:
  auth_selectedType: "vertex-ai"

Telemetry (`telemetry`)

Override telemetry settings for this template or agent. These merge on top of any telemetry configuration defined in settings.yaml (global or grove scope), using last-write-wins semantics.

telemetry:
  enabled: true
  cloud:
    endpoint: "monitoring.googleapis.com:443"
  filter:
    events:
      exclude:
        - "agent.user.prompt"
  resource:
    service.name: "my-specialized-agent"

See the Orchestrator Settings Reference for the full field reference and the Metrics guide for how telemetry settings merge across scopes.

Kubernetes Specifics (`kubernetes`)

Overrides for Kubernetes runtimes.

kubernetes:
  namespace: "custom-ns"
  serviceAccountName: "workload-identity-sa"
  runtimeClassName: "gvisor"

Resolution Logic

When an agent starts:

Template Load: Scion loads scion-agent.yaml from the selected template.
Harness Resolution: It resolves the harness_config against the active profile’s harness_configs map in settings.yaml.
Overrides: CLI flags (e.g., --image, --env) override values in scion-agent.yaml.
Final Config: The resolved configuration is written to the agent’s runtime directory.