​

Settings Reference (~/.si/settings.toml)

~/.si/settings.toml

​

Precedence

1. CLI flags
2. ~/.si/settings.toml
3. Environment variables
4. Built-in defaults

​

CLI color output

• section headings: cyan
• commands/examples: magenta
• flags/prompts: yellow
• labels: blue
• success: green
• warnings: yellow
• errors: red
• muted text: gray

• SI_CLI_COLOR=always: force color
• SI_CLI_COLOR=auto: default behavior
• SI_CLI_COLOR=never: disable color
• NO_COLOR=1: disable color

​

Schema

​

Top-level

• schema_version (int): settings schema version. Current value: 1.

​

[paths]

• paths.root (string): default ~/.si
• paths.settings_file (string): default ~/.si/settings.toml
• paths.codex_profiles_dir (string): default ~/.si/codex/profiles
• paths.workspace_root (string): optional host directory containing sibling repos. Used by SI runtime commands when flags are omitted.

• ~/.si/warmup/state.json (reconcile state/feedback loop)
• ~/.si/warmup/autostart.v1 (warmup scheduler enabled marker)
• ~/.si/warmup/disabled.v1 (warmup scheduler disabled marker)
• ~/.si/logs/warmup.log (JSONL operational log)

​

[codex]

• Every si codex worker must resolve to a predefined entry under [codex.profiles.entries.<id>].
  • si codex profile add|show|list|login|swap|remove manages the profile registry in ~/.si/settings.toml.
• codex.workspace (string): host path for workspace bind.
  • If unset, si codex spawn resolves from --workspace or current directory.
  • On first interactive use, SI prompts to save the resolved path into ~/.si/settings.toml.
• codex.workdir (string): worker working directory
• codex.profile (string): legacy compatibility field for the most recently selected Codex profile.
• Profile metadata is intentionally narrow here: the entry records identity and auth file location, while actual runtime behavior stays under si codex ....
• Worker-slot behavior is command-level:
  • si codex spawn|respawn --profile <profile> --slot <slot>
  • si codex shell|tail|tmux|stop|remove --profile <profile> --slot <slot>
  • si codex repair-auth --profile <profile> --slot <slot> for in-place Fort runtime repair

​

[codex.profiles]

• codex.profiles.active (string): the most recently swapped/selected profile for profile-scoped Fort runtime auth and related host state

[codex.profiles.entries.<id>]

• name (string): profile display name
• email (string): profile email
• auth_path (string): path to auth.json
• auth_updated (string): RFC3339 timestamp of auth.json

​

[fort]

• fort.repo (string): source repo path used when si fort --build is enabled
• fort.bin (string): fort binary path used by wrapper execution
• fort.build (bool): default build-before-run behavior for wrapper calls
• fort.host (string): hosted Fort endpoint URL (must be HTTPS for production runtime)
• fort.runtime_host (string): Fort endpoint URL intended for runtime workers (defaults to fort.host when unset)

• si fort config show reads these values.
• si fort config set ... writes these values to settings.
• si fort injects --host from [fort].host when no explicit native --host flag is passed.
• si fort prefers the profile Fort session under CODEX_HOME/fort/ when CODEX_HOME is set by a managed Codex profile runtime.
• si fort does not accept caller-supplied FORT_TOKEN_PATH / FORT_REFRESH_TOKEN_PATH as a normal runtime fallback and does not fall back to the active Codex profile outside si codex spawn / si codex shell.
• si fort fails loudly for runtime secret commands when no usable runtime session exists or runtime refresh fails; it does not silently fall back to host/bootstrap admin auth.
• si fort uses host/bootstrap admin token files at ~/.si/fort/bootstrap/admin.token and ~/.si/fort/bootstrap/admin.refresh.token only for explicit admin/provisioning commands.
• Treat bootstrap/admin auth as recovery-only; day-to-day Fort use should run through profile-scoped runtime token files provisioned by si codex spawn or si codex shell.
• Codex profile provisioning explicitly requests a 30d Fort refresh-session TTL even if Fort’s general default refresh-session TTL is shorter.
• Runtime worker token state remains file-backed under:
  • ~/.si/codex/profiles/<profile>/fort/ for the primary slot
  • ~/.si/codex/profiles/<profile>/workers/<slot>/fort/ for non-primary slots
  • Fort runtime agent IDs are slot-aware: si-codex-<profile> for primary, si-codex-<profile>--<slot> for non-primary slots
  • profile refresh tokens must be rotated in place.

​

[viva]

• viva.repo (string): source repo path used by si viva --repo, configured repo resolution, or build fallback
• viva.bin (string): native Viva binary path used by wrapper execution
• viva.build (bool): default build-before-run behavior for wrapper calls

• si viva config show reads these wrapper values.
• si viva config set --repo <PATH> --bin <PATH> --build <true|false> writes these wrapper values to ~/.si/viva/settings.toml unless --settings-file is supplied.
• Wrapper options such as si viva --repo <PATH> --build -- version must appear before native Viva args.

​

[viva.tunnel]

• viva.tunnel.default_profile (string): default profile appended to native viva tunnel ... commands when no native --profile argument is present
• viva.tunnel.profiles.<name> (table): stored tunnel profile metadata consumed by the wrapper

• si viva config tunnel show reads configured tunnel profiles.
• si viva config tunnel import --profile <name> --file <PATH> [--set-default] imports one native Viva tunnel profile table into ~/.si/viva/settings.toml.
• si viva config tunnel default --profile <name> changes the wrapper default profile and refuses missing profile names.
• si viva config tunnel import copies the raw profile TOML table so native Viva-owned fields are preserved.

​

[surf]

~/.si/surf/si.settings.toml

• surf.repo (string): source repo path used by si surf --repo, configured repo resolution, or build fallback
• surf.bin (string): native Surf binary path used by wrapper execution
• surf.build (bool): default build-before-run behavior for wrapper calls
• surf.settings_file (string): native Surf settings file path passed through where native Surf supports it
• surf.state_dir (string): native Surf state directory path passed through where native Surf supports it
• surf.vnc_password_fort_key (string): Fort key used to inject SURF_VNC_PASSWORD for si surf start
• surf.vnc_password_fort_repo (string): Fort repo scope for the noVNC password key; defaults to surf when a key is configured
• surf.vnc_password_fort_env (string): Fort env scope for the noVNC password key; defaults to dev when a key is configured

• si surf wrapper config show reads SI wrapper values.
• si surf wrapper config set --repo <PATH> --bin <PATH> --build <true|false> writes SI wrapper values to ~/.si/surf/si.settings.toml unless --settings-file is supplied.
• si surf config ... is native Surf config passthrough and does not write SI wrapper settings.
• Wrapper options such as si surf --repo <PATH> --build -- version must appear before native Surf args.
• si surf sets SI_SURF_WRAPPED=1 for native Surf execution.

​

[surf.tunnel]

• surf.tunnel.name (string): Surf tunnel runtime name
• surf.tunnel.mode (string): quick or token
• surf.tunnel.fort_key (string): Fort key for tunnel token material when supported by native Surf
• surf.tunnel.vault_key (string): legacy compatibility alias for older settings only

​

External orbit settings

​

Example

schema_version = 1

[paths]
root = "~/.si"
settings = "~/.si/settings.toml"
codex_profiles_dir = "~/.si/codex/profiles"
workspace_root = "~/code"

[codex]
image = "aureuma/si:local"
network = "si"
workspace = "/path/to/your/repo"
workdir = "/workspace"
profile = "profile-alpha"

[codex.profiles]
active = "profile-alpha"

[codex.profiles.entries.profile-alpha]
name = "🧪 Profile Alpha"
email = "example@example.com"
auth_path = "~/.si/codex/profiles/profile-alpha/auth.json"
auth_updated = "2026-01-26T00:00:00Z"