Settings Reference (~/.si/settings.toml)
si reads a single TOML file for user-facing configuration. The canonical path is:
si codex profile ... writes Codex profile metadata here so profile registry state, Fort profile binding, and default runtime selection all share one source of truth.
Precedence
When supported by a command, values resolve in this order:- CLI flags
~/.si/settings.toml- Environment variables
- Built-in defaults
CLI color output
SI CLI help and text-mode output share one semantic color palette:- 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 colorSI_CLI_COLOR=auto: default behaviorSI_CLI_COLOR=never: disable colorNO_COLOR=1: disable color
Schema
The file is a standard TOML document.schema_version is reserved for future migrations.
Top-level
schema_version(int): settings schema version. Current value:1.
[paths]
Reference paths for the local .si directory layout.
paths.root(string): default~/.sipaths.settings_file(string): default~/.si/settings.tomlpaths.codex_profiles_dir(string): default~/.si/codex/profilespaths.workspace_root(string): optional host directory containing sibling repos. Used by commands such assi orbit github git ...,si remote-control, andsi viva node bootstrapwhen flags are omitted.
~/.si:
~/.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)
si codex warmup ....
Warmup only inspects persistent Codex container status and schedules the next run from the reported reset windows with a small jitter.
[codex]
Defaults for si codex profile-bound container commands.
- Every
si codexcontainer must resolve to a predefined entry under[codex.profiles.entries.<id>]. si codex profile add|show|list|login|swap|removemanages the profile registry in~/.si/settings.toml.codex.image(string): docker image forsi codex spawn(default:aureuma/si:local)codex.network(string): docker network namecodex.workspace(string): host path for workspace bind.- If unset,
si codex spawnresolves from--workspaceor current directory. - On first interactive use, SI prompts to save the resolved path into
~/.si/settings.toml.
- If unset,
codex.workdir(string): container working directorycodex.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/container behavior stays under
si codex ....
[codex.profiles]
Profile metadata tracked in settings.
codex.profiles.active(string): the most recently swapped/selected profile for profile-scoped Fort runtime auth and related host state
[codex.profiles.entries.<id>]
Per-profile entry keyed by profile ID (for example profile-alpha). These entries are created and updated by si codex profile add and any later profile metadata sync flows.
name(string): profile display nameemail(string): profile emailauth_path(string): path to auth.jsonauth_updated(string): RFC3339 timestamp of auth.json
[fort]
Defaults for the si fort wrapper (hosted Fort API access).
fort.repo(string): source repo path used whensi fort --buildis enabledfort.bin(string): fort binary path used by wrapper executionfort.build(bool): default build-before-run behavior for wrapper callsfort.host(string): hosted Fort endpoint URL (must be HTTPS for production runtime)fort.container_host(string): Fort endpoint URL intended for runtime containers (defaults tofort.hostwhen unset)
si fort config showreads these values.si fort config set ...writes these values to settings.si fortinjects--hostfrom[fort].hostwhen no explicit native--hostflag is passed.si fortprefers runtime file-path auth fromFORT_TOKEN_PATH/FORT_REFRESH_TOKEN_PATHwhen those paths are set in the caller environment, and refreshes that session in place when possible.si fortotherwise prefers the active Codex profile Fort session underpaths.codex_profiles_dir/<profile>/fort/and refreshes that file-backed session in place when possible.si fortonly falls back to the host/bootstrap admin token files at~/.si/fort/bootstrap/admin.tokenand~/.si/fort/bootstrap/admin.refresh.tokenwhen no runtime session is available or runtime refresh fails.- Treat bootstrap/admin auth as recovery-only; day-to-day Fort use should run through profile-scoped runtime token files.
- Runtime container token state remains file-backed; pass explicit file paths to native Fort commands instead of token-value env vars.
[stripe]
Defaults for si orbit stripe account and environment context.
stripe.organization(string): optional organization labelstripe.default_account(string): default account alias (oracct_id)stripe.default_env(string):liveorsandbox(default:sandbox)stripe.log_file(string): JSONL log path for Stripe bridge request/response events (default:~/.si/logs/stripe.log)
[stripe.accounts.<alias>]
Per-account Stripe settings.
id(string): Stripe account id (acct_...) used for scoped callsname(string): display namelive_key(string): direct live API key (prefer env refs instead)sandbox_key(string): direct sandbox API key (prefer env refs instead)live_key_env(string): env var name holding the live keysandbox_key_env(string): env var name holding the sandbox key
si orbit stripe:
--api-key(or--live-api-key/--sandbox-api-keyfor sync)- Account settings key (
live_key/sandbox_key) - Account settings env ref (
live_key_env/sandbox_key_env) - Environment-specific env fallback (
SI_STRIPE_LIVE_API_KEY/SI_STRIPE_SANDBOX_API_KEY) - Generic env fallback (
SI_STRIPE_API_KEY)
SI_STRIPE_ACCOUNT can provide default account selection when settings do not specify one.
[github]
Defaults for si orbit github (GitHub App or OAuth token auth).
github.default_account(string): default account aliasgithub.default_auth_mode(string):apporoauth(default:app)github.api_base_url(string): API base URL (default:https://api.github.com)github.default_owner(string): default owner/org for commands that accept owner fallbackgithub.vault_env(string): vault env hint (default:dev)github.vault_file(string): optional explicit vault file pathgithub.log_file(string): JSONL log path for GitHub bridge request/response events (default:~/.si/logs/github.log)
[github.accounts.<alias>]
Per-account GitHub settings.
name(string): display nameowner(string): default owner/org for this accountapi_base_url(string): per-account API base URL (supports GHES)auth_mode(string):apporoauth(overrides global default for this account)vault_prefix(string): env key prefix override (exampleGITHUB_CORE_)oauth_access_token(string): direct OAuth token (prefer env refs)oauth_token_env(string): env var with OAuth tokenapp_id(int): direct app id (prefer env refs for secretless settings)app_id_env(string): env var with app idapp_private_key_pem(string): direct private key PEM (prefer env refs)app_private_key_env(string): env var with private key PEMinstallation_id(int): explicit installation idinstallation_id_env(string): env var with installation id
si orbit github:
- CLI override (
--auth-modewhere available) - Account settings (
auth_mode) - Env fallback (
GITHUB_AUTH_MODE, thenGITHUB_DEFAULT_AUTH_MODE) - Global settings (
github.default_auth_mode)
si orbit github in app mode:
- CLI overrides (
--app-id,--app-key,--installation-id) - Account settings (
app_id,app_private_key_pem,installation_id) - Account env refs (
app_id_env,app_private_key_env,installation_id_env) - Account-prefix env keys (
GITHUB_<ACCOUNT>_APP_ID,GITHUB_<ACCOUNT>_APP_PRIVATE_KEY_PEM,GITHUB_<ACCOUNT>_INSTALLATION_ID) - Global env fallbacks (
GITHUB_APP_ID,GITHUB_APP_PRIVATE_KEY_PEM,GITHUB_INSTALLATION_ID)
si orbit github in oauth mode:
- CLI override (
--tokenwhere available) - Account settings (
oauth_access_token) - Account env ref (
oauth_token_env) - Account-prefix env keys (
GITHUB_<ACCOUNT>_OAUTH_ACCESS_TOKEN,GITHUB_<ACCOUNT>_TOKEN) - Global env fallbacks (
GITHUB_OAUTH_TOKEN,GITHUB_TOKEN,GH_TOKEN)
[cloudflare]
Defaults for si orbit cloudflare (token auth with multi-account and env context labels).
cloudflare.default_account(string): default account aliascloudflare.default_env(string):prod,staging, ordev(default:prod)cloudflare.api_base_url(string): API base URL (default:https://api.cloudflare.com/client/v4)cloudflare.vault_env(string): vault env hint (default:dev)cloudflare.vault_file(string): optional explicit vault file pathcloudflare.log_file(string): JSONL log path for Cloudflare bridge request/response events (default:~/.si/logs/cloudflare.log)
[cloudflare.accounts.<alias>]
Per-account Cloudflare context and env-key pointers.
name(string): display nameaccount_id(string): Cloudflare account idaccount_id_env(string): env var with account idapi_base_url(string): per-account API base URL overridevault_prefix(string): env key prefix override (exampleCLOUDFLARE_CORE_)default_zone_id(string): default zone id fallbackdefault_zone_name(string): default zone name fallbackprod_zone_id(string): zone id used whenenv=prodstaging_zone_id(string): zone id used whenenv=stagingdev_zone_id(string): zone id used whenenv=devapi_token_env(string): env var with API token
si orbit cloudflare is vault-compatible and token-only:
- CLI overrides (
--api-token,--account-id,--zone-id) - Account settings (
account_id, env-mapped zone ids, defaults) - Account env refs (
account_id_env,api_token_env) - Account-prefix env keys (
CLOUDFLARE_<ACCOUNT>_API_TOKEN,CLOUDFLARE_<ACCOUNT>_ACCOUNT_ID,CLOUDFLARE_<ACCOUNT>_PROD_ZONE_ID,CLOUDFLARE_<ACCOUNT>_STAGING_ZONE_ID,CLOUDFLARE_<ACCOUNT>_DEV_ZONE_ID) - Global env fallbacks (
CLOUDFLARE_API_TOKEN,CLOUDFLARE_ACCOUNT_ID,CLOUDFLARE_ZONE_ID)
[gcp]
Defaults for si orbit gcp (Service Usage, IAM, API keys, Gemini, and Vertex AI).
gcp.default_account(string): default account aliasgcp.default_env(string):prod,staging, ordev(default:prod)gcp.api_base_url(string): default API base URL used bysi orbit gcp service(default:https://serviceusage.googleapis.com)gcp.log_file(string): JSONL log path for GCP bridge events (default:~/.si/logs/gcp-serviceusage.log)
[gcp.accounts.<alias>]
Per-account GCP context and env-key pointers.
name(string): display namevault_prefix(string): env key prefix override (exampleGCP_CORE_)project_id(string): default Google Cloud project idproject_id_env(string): env var with project idaccess_token_env(string): env var with OAuth access tokenapi_key_env(string): env var with API key (used by Gemini API-key mode)api_base_url(string): per-account API base URL override
si orbit gcp project id:
- CLI override (
--project) - Account settings (
project_id) - Account env ref (
project_id_env) - Account-prefix env key (
GCP_<ACCOUNT>_PROJECT_ID) - Global env fallbacks (
GCP_PROJECT_ID,GOOGLE_CLOUD_PROJECT)
si orbit gcp OAuth token:
- CLI override (
--access-token) - Account env ref (
access_token_env) - Account-prefix env key (
GCP_<ACCOUNT>_ACCESS_TOKEN) - Global env fallbacks (
GOOGLE_OAUTH_ACCESS_TOKEN,GCP_ACCESS_TOKEN)
si orbit gcp gemini):
- CLI override (
--api-key) - Account env ref (
api_key_env) - Account-prefix env key (
GCP_<ACCOUNT>_API_KEY) - Global env fallbacks (
GEMINI_API_KEY,GOOGLE_API_KEY,GCP_API_KEY)
[google]
Defaults for si orbit google places and si orbit google youtube (multi-account and env context labels).
google.default_account(string): default account aliasgoogle.default_env(string):prod,staging, ordev(default:prod)google.api_base_url(string): API base URL (default:https://places.googleapis.com)google.vault_env(string): vault env hint (default:dev)google.vault_file(string): optional explicit vault file pathgoogle.log_file(string): shared JSONL log path override for Google bridges. If unset, Places defaults to~/.si/logs/google-places.logand YouTube defaults to~/.si/logs/google-youtube.log.
[google.accounts.<alias>]
Per-account Google Places context and env-key pointers.
name(string): display nameproject_id(string): default Google Cloud project idproject_id_env(string): env var with project idapi_base_url(string): per-account API base URL overridevault_prefix(string): env key prefix override (exampleGOOGLE_CORE_)places_api_key_env(string): env var with generic Places API keyprod_places_api_key_env(string): env var with prod Places API keystaging_places_api_key_env(string): env var with staging Places API keydev_places_api_key_env(string): env var with dev Places API keydefault_region_code(string): default CLDR region codedefault_language_code(string): default BCP-47 language code
si orbit google places is vault-compatible and API-key based:
- CLI overrides (
--api-key,--project-id) - Account settings (
project_id) - Account env refs (
project_id_env,places_api_key_env,prod_places_api_key_env,staging_places_api_key_env,dev_places_api_key_env) - Account-prefix env keys (
GOOGLE_<ACCOUNT>_PLACES_API_KEY,GOOGLE_<ACCOUNT>_PROD_PLACES_API_KEY,GOOGLE_<ACCOUNT>_STAGING_PLACES_API_KEY,GOOGLE_<ACCOUNT>_DEV_PLACES_API_KEY,GOOGLE_<ACCOUNT>_PROJECT_ID) - Global env fallbacks (
GOOGLE_PLACES_API_KEY,GOOGLE_PROJECT_ID)
[google.youtube]
Defaults for si orbit google youtube (YouTube Data API v3).
google.youtube.api_base_url(string): API base URL (default:https://www.googleapis.com)google.youtube.upload_base_url(string): upload API base URL (default:https://www.googleapis.com/upload)google.youtube.default_auth_mode(string):api-keyoroauth(default:api-key)google.youtube.upload_chunk_size_mb(int): default chunk hint for upload flows (default:16)
[google.youtube.accounts.<alias>]
Per-account YouTube context and env-key pointers.
name(string): display nameproject_id(string): default Google Cloud project idproject_id_env(string): env var with project idvault_prefix(string): env key prefix override (exampleGOOGLE_CORE_)youtube_api_key_env(string): env var with generic YouTube API keyprod_youtube_api_key_env(string): env var with prod YouTube API keystaging_youtube_api_key_env(string): env var with staging YouTube API keydev_youtube_api_key_env(string): env var with dev YouTube API keyyoutube_client_id_env(string): env var with OAuth client idyoutube_client_secret_env(string): env var with OAuth client secretyoutube_redirect_uri_env(string): env var with OAuth redirect uriyoutube_refresh_token_env(string): env var with OAuth refresh tokendefault_region_code(string): default region codedefault_language_code(string): default language code
si orbit google youtube is vault-compatible and supports both API key and OAuth:
- CLI overrides (
--api-key,--project-id,--client-id,--client-secret,--redirect-uri,--access-token,--refresh-token) - Account settings (
project_id) - Account env refs (
project_id_env,youtube_api_key_env, env-specific api key refs, OAuth refs) - Account-prefix env keys (
GOOGLE_<ACCOUNT>_YOUTUBE_API_KEY,GOOGLE_<ACCOUNT>_PROD_YOUTUBE_API_KEY,GOOGLE_<ACCOUNT>_STAGING_YOUTUBE_API_KEY,GOOGLE_<ACCOUNT>_DEV_YOUTUBE_API_KEY,GOOGLE_<ACCOUNT>_YOUTUBE_CLIENT_ID,GOOGLE_<ACCOUNT>_YOUTUBE_CLIENT_SECRET,GOOGLE_<ACCOUNT>_YOUTUBE_REDIRECT_URI,GOOGLE_<ACCOUNT>_YOUTUBE_ACCESS_TOKEN,GOOGLE_<ACCOUNT>_YOUTUBE_REFRESH_TOKEN,GOOGLE_<ACCOUNT>_PROD_YOUTUBE_REFRESH_TOKEN,GOOGLE_<ACCOUNT>_STAGING_YOUTUBE_REFRESH_TOKEN,GOOGLE_<ACCOUNT>_DEV_YOUTUBE_REFRESH_TOKEN) - Global env fallbacks (
GOOGLE_YOUTUBE_API_KEY,GOOGLE_YOUTUBE_CLIENT_ID,GOOGLE_YOUTUBE_CLIENT_SECRET,GOOGLE_YOUTUBE_REDIRECT_URI,GOOGLE_YOUTUBE_ACCESS_TOKEN,GOOGLE_YOUTUBE_REFRESH_TOKEN,GOOGLE_PROJECT_ID)
si orbit google youtube auth login is stored at:
~/.si/google/youtube/oauth_tokens.json
[vault]
Defaults for si vault.
vault.file(string): default dotenv file used when--env-file/--fileis not provided (default:.env)vault.trust_store(string): optional trust store path for recipient fingerprint checksvault.audit_log(string): optional local JSONL audit sink (empty by default)vault.key_backend(string): key backend for SI Vault identity material (keyring/file)vault.key_file(string): key file path whenvault.key_backend=\"file\"vault.sync_backend(string): Fort-only mode; onlyfortis accepted.
[viva]
Defaults for si viva wrapper and Viva tunnel profile config.
viva.repo(string): default localvivarepo path.viva.bin(string): defaultvivabinary path.viva.build(bool): default--buildbehavior for wrapper executions.
[viva.tunnel]
viva.tunnel.default_profile(string): default profile used byviva tunnelwhen--profileis omitted.
[viva.tunnel.profiles.<name>]
Per-profile Cloudflare tunnel runtime settings consumed by viva tunnel.
name(string): logical tunnel name.container_name(string): docker container name for cloudflared.tunnel_id_env_key(string): dotenv key for Cloudflare tunnel id (default:VIVA_CLOUDFLARE_TUNNEL_ID).credentials_env_key(string): dotenv key for tunnel credentials JSON (default:CLOUDFLARE_TUNNEL_CREDENTIALS_JSON).metrics_addr(string): cloudflared metrics bind address.image(string): cloudflared image (default:cloudflare/cloudflared:latest).network_mode(string): docker network mode (default:host).no_autoupdate(bool): pass--no-autoupdate.pull_image(bool): pull image before run.runtime_dir(string): host runtime directory for generated files.vault_env_file(string): encrypted dotenv file path used bysi fort.vault_repo(string): repo argument passed tosi fort(default:viva).vault_env(string): env argument passed tosi fort(default:dev).
[[viva.tunnel.profiles.<name>.routes]]
hostname(string, optional): ingress hostname.service(string, required): upstream service URL orhttp_status:404.
[shell.prompt]
Prompt rendering for si codex shell interactive shells. This applies without modifying .bashrc.
shell.prompt.enabled(bool): enable/disable prompt customizationshell.prompt.git_enabled(bool): include git branch when availableshell.prompt.prefix_template(string): template for profile prefix. Use{profile}placeholder.shell.prompt.format(string): layout template. Supported placeholders:{prefix},{cwd},{git},{symbol}shell.prompt.symbol(string): prompt symbol (e.g.$or❯)
[shell.prompt.colors]
Color tokens for prompt components. Supported values:
- Basic names:
black,red,green,yellow,blue,magenta,cyan,white - Bright variants:
bright-black,bright-red,bright-green,bright-yellow,bright-blue,bright-magenta,bright-cyan,bright-white resetansi:<code>where<code>is an ANSI numeric color code (e.g.ansi:0;36)raw:<value>to pass a raw escape sequence
shell.prompt.colors.profileshell.prompt.colors.cwdshell.prompt.colors.gitshell.prompt.colors.symbolshell.prompt.colors.errorshell.prompt.colors.reset

