Menu
简体中文
On this page

Sigil Configuration Guide

Docs home · Permissions and sandbox · Appearance · Advanced configuration · Field reference · Providers · 简体中文

This is the recommended starting point for shared Sigil configuration. It covers where configuration lives, the smallest useful setup, workspace and storage choices, and where to find a focused setting. Provider credentials and provider-specific options are on the Provider guide.

Choose The Right Page

You want to…Start here
Set up Sigil, select a workspace, or find the config fileThis page
Change approvals, network access, external paths, or sandboxingPermissions and sandbox
Change the TUI theme, code highlighting, or colorsAppearance
Configure tasks, checks, memory, code intelligence, terminal, plugins, or MCPAdvanced configuration
Look up an exact sigil.toml field or valueConfiguration reference
Select a model service, endpoint, or credentialProvider guide

Resolution Order

Sigil resolves configuration in this order:

  1. --config <path>
  2. sigil.toml in the user-visible Sigil configuration directory

The default user config is:

~/.sigil/sigil.toml

Quick Setup writes this user config. A sigil.toml in the workspace is not loaded automatically; pass --config <path> when you deliberately want to use a local experimental config.

Minimal Path

For normal interactive use, start Sigil in the project you want to work on and complete Quick Setup:

cd /path/to/workspace
sigil

For temporary use or CI, choose a provider and export its provider-specific credential before launch. The Provider guide contains the correct variable and copyable examples for each service; there is no one provider-neutral API-key variable.

If you prefer a small hand-written shared config, start here:

[workspace]
root = "."

[agent]
tool_timeout_secs = 30

[appearance]
theme = "sigil_dark"
syntax_theme = "auto"
usage_cost_currency = "auto"

Then add the provider block from the provider page you selected. Copyable examples are available under docs/examples/config.

Workspace

[workspace]
root = "."

workspace.root = "." resolves to the directory where you launched sigil, which lets one user config follow the repository you opened. File tools are limited to this workspace. They reject parent-path escapes, absolute paths, and symlinks that point outside it.

Use the Permissions and sandbox guide before allowing a path outside the workspace or changing local command behavior.

Local Command Shell

Sigil resolves one native shell when the built-in tools are registered. On Windows it prefers pwsh.exe and falls back to Windows PowerShell (powershell.exe); on macOS and Linux it uses sh. The tool is still named bash for provider compatibility, but its description, approval analysis, result metadata, and terminal cards report the actual program and dialect.

PowerShell commands must use PowerShell syntax such as $env:NAME and $null; Bash syntax is not translated. An explicit terminal_start.shell accepts the modeled POSIX shells, PowerShell, or cmd.exe; unknown shells fail before spawn. Prefer Sigil's file tools for portable reads and edits. Run sigil doctor and inspect terminal:shell when command syntax behaves differently from the host you expected.

Storage And Session Paths

[storage]
state_root = "auto"
cache_root = "auto"

[session]
# log_dir = "sessions"

[session.retention]
max_sessions = 500
max_bytes = 2147483648
expire_older_than_ms = 15552000000 # 180 days

state_root holds durable per-user Sigil state such as session-adjacent records and artifacts. cache_root holds rebuildable scratch data. session.log_dir changes only session-log placement for the current workspace; it does not replace the state root.

Session retention is a policy for an explicit maintenance preview and confirmation. Normal startup, runs, resume, and sigil serve never apply it automatically. Current, active, pinned, unsupported, and drifting sessions are protected. See Manage saved sessions for the TUI flow.

SIGIL_STATE_HOME and SIGIL_CACHE_HOME override their corresponding roots. Prefer an absolute path for an override in sigil.toml. Repository-local reusable resources stay under the fixed .sigil/ directory; use Advanced configuration for those resources.

Use Doctor When Setup Looks Wrong

Run:

sigil doctor

Inside the TUI, /doctor shows the same report. It checks configuration loading, workspace resolution, session location, provider and credential source, configured MCP servers, code-intelligence readiness, and terminal compatibility. It never prints a secret value and includes remediation guidance for warnings and errors.

Use the same config override when you launch with a non-default config:

sigil --config ./sigil.toml doctor

Next