Configuration Overview

Scion uses a multi-layered configuration system to manage orchestrator behavior, agent execution, and server operations.

Key Configuration Files

File	Purpose	Scope	Reference
settings.yaml	Orchestrator Settings. Defines profiles, runtimes, and harness configurations.	Global (~) or Project (.scion)	Orchestrator Settings
scion-agent.yaml	Agent Blueprint. Defines the configuration for a specific agent or template.	Template or Agent	Agent Configuration
state.yaml	Runtime State. Tracks system state like sync timestamps.	Project (.scion)	N/A (Managed by Scion)

YAML or JSON

Scion accepts both YAML and JSON for settings and scion-agent files. YAML is preferred: scion init writes settings.yaml, and when several files coexist the loader resolves them in the order settings.yaml → settings.yml → settings.json (the same precedence applies to scion-agent.*). Use whichever format you prefer, but keep the content valid for that format — do not place JSON objects inside a .yaml file. Both formats validate against the settings JSON schema.

Server Configuration

Server configuration (for Hub and Runtime Broker) is now integrated into settings.yaml under the server key.

• Server Configuration Reference

Telemetry Configuration

Telemetry settings control agent observability — trace collection, cloud forwarding, privacy filtering, and debug output. These are configured via the telemetry block in settings.yaml and can be overridden per-template or per-agent in scion-agent.yaml.

• Orchestrator Settings — Telemetry
• Metrics & OpenTelemetry Guide

Project Settings

In a Hub-managed architecture, Project Settings are maintained by the Hub database and managed via the Web Dashboard or API, rather than a local file. These settings define constraints and capabilities for agents operating within a specific project.

Key configuration areas include:

• General Settings: The project’s description, default branch, and external Git repository URLs for template synchronization.
• Agent Limits: Defines maximum resource constraints for agents in the project, including maximum concurrency, runtime duration limits, and maximum workspace storage. These values pre-populate the agent creation form.
• Resources & Plugins: Defines authorized Runtime Brokers and configures Message Broker plugins for the project.

When a project is exported or managed locally in a standalone environment, some of these settings may be serialized into .scion/state.yaml or related project files.

Configuration Hierarchy

Scion resolves settings in the following order (highest priority first):

1. CLI Flags: (e.g., scion start --profile remote)
2. Environment Variables: SCION_* overrides.
3. Project Settings: .scion/settings.yaml (Project level).
4. Global Settings: ~/.scion/settings.yaml (User level).
5. Defaults: System built-ins.

Unrecognized Key Warnings

When loading settings files, Scion logs a warning for any unrecognized key it encounters. This helps catch typos (e.g., telemtry instead of telemetry) and outdated keys from earlier configuration schemas — without failing startup. The warnings appear in server or CLI startup output and do not prevent the rest of the configuration from loading normally.

Migration

To migrate legacy configuration files to the new schema v1 format:

# Migrate legacy settings (a server.yaml next to a legacy settings.yaml is
# merged under the server key)
scion config migrate

A server.yaml next to a settings.yaml that already has schema_version is not merged automatically: copy its contents under a top-level server: key in settings.yaml and remove server.yaml (a --server flag is tracked in ptone/scion#3116).