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 the Hub telemetry configuration. A template’s telemetry block is ignored, and an agent’s own config can only turn telemetry on or off.

• 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 through a single loader in the following order (highest priority first):

1. CLI Flags: (e.g., scion start --profile remote)
2. Environment Variables: SCION_* overrides (mapped to settings keys with _ as a path separator; an exported empty value counts as unset).
3. Project Settings: .scion/settings.yaml (in-repo) and, for git projects with split storage, ~/.scion/project-configs/<slug>__<id>/.scion/settings.yaml (external project config).
4. Global Settings: ~/.scion/settings.yaml (User level).
5. Defaults: System built-ins.

Whole-file rewrites of settings.yaml (such as scion config set, scion config unset, scion config migrate, and Hub link updates) take the settings-directory lock (an exclusive lock on .settings.lock in that directory, waited for up to 10 seconds) and replace the file atomically via a temporary file in the same directory, preserving existing file permissions.

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

Legacy settings files (those without schema_version) are converted to the v1 shape at their own layer when read, keeping only keys that the file itself sets; a versioned file’s legacy camelCase hub.projectId is also read as a fallback when hub.project_id is absent. To rewrite legacy configuration files on disk to the 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.