Configuration Files

ZeroSphere stores configuration in two locations depending on the file type and platform.

File Locations

Application-managed configuration:

Windows:

%APPDATA%\Roaming\zerosphere-nightly\
├── settings.toml        # Editor and UI settings
├── config.toml          # Agent permissions
└── .env                 # API keys

User-managed data:

%USERPROFILE%\.zerosphere\
├── plan/                # Planning mode artifacts
├── recordings/          # Session recordings (if enabled)
└── rules/               # Custom instruction files

MCP server configuration:

%USERPROFILE%\.zerosphere\mcp/mcp.json

Project-level overrides (optional, committed to version control):

your-project/
└── .zerosphere/
    └── settings.toml    # Overrides user settings for this project only

Project settings take precedence over user settings. User settings take precedence over built-in defaults.

settings.toml

Editor behavior and appearance. Most settings are configurable via Settings in the UI — the TOML file is the underlying store.

[core]
modal = false                          # Vim keybindings
color-theme = "ZeroSphere Dark"
icon-theme = "ZeroSphere Codicons"

[ui]
scale = 1.0
font-size = 13

[editor]
font-size = 14
tab-width = 4
format-on-save = false
autosave-on-focus-lost = true

[terminal]
font-size = 14
line-height = 1.1

config.toml

Agent permissions. Editable via Settings > AI or directly.

[permissions]
outside_workspace_access_enabled = false
ignored_workspace_file_access_enabled = false

[permissions.terminal]
run_command_mode = "let_model_decide"
os_run_in_session_mode = "ask_each_time"

[permissions.os_tools]
os_create_virtual_session_mode = "ask_each_time"
os_create_main_display_session_mode = "ask_each_time"
os_bind_window_mode = "ask_each_time"
os_bind_window_allow_paths = []
os_bind_window_deny_paths = []

[permissions.commands]
always_run_commands = []
deny_commands = []
os_always_run_commands = []
os_deny_commands = []

Mode values:

  • run_command_mode, os_run_in_session_mode, os_bind_window_mode: ask_each_time | run_always | let_model_decide
  • os_create_virtual_session_mode: ask_each_time | always_launch
  • os_create_main_display_session_mode: ask_each_time | always_take_control

See Permissions for what each setting controls.

.env

Stores API keys for native providers and custom model profiles. Managed by the application when you save keys in Settings > AI > API Keys or add a custom model profile in Settings > AI > Custom Models.

Keys you can set here:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AI...
TAVILY_API_KEY=tvly-...
OPENROUTER_API_KEY=sk-or-...

Do not commit this file. It contains your API keys.

Useful Operations

Reset editor settings to defaults:

Delete or rename settings.toml and restart ZeroSphere. It will recreate the file with built-in defaults.

Troubleshooting

Settings not applying: Check if a workspace .zerosphere/settings.toml is overriding your user settings.

TOML parse error: The error message includes the line number. Fix the syntax and restart ZeroSphere.

config.toml changes not taking effect: ZeroSphere reloads config.toml on each agent run. A restart is not required after editing permissions.