Settings file reference

Radius reads repository settings from two TOML files:

File	Purpose	Version control
`.radius/settings.toml`	Shared repository behavior.	Commit it.
`.radius/settings.local.toml`	Machine-specific overrides and secrets.	Keep it private.

Both files use version = 1. Add the schema URL for editor validation and autocomplete:

"$schema" = "https://radiusbrowser.com/schemas/settings.repo.schema.json"
version = 1

Complete example

"$schema" = "https://radiusbrowser.com/schemas/settings.repo.schema.json"
version = 1

[environment.variables]
NODE_ENV = "development"
DEV_SERVER_PORT = "5180"

[files]
include = [".env.local", "config/development.json"]

[git]
base_ref = "origin/main"
remote = "origin"
delete_branch_on_archive = false
push_auto_setup_remote = true

[scripts]
startup = "./scripts/open-radius-workspace.sh"
setup = "pnpm install"
archive = "pnpm run cleanup"

[scripts.run.dev]
name = "Development server"
command = "pnpm dev"

Root fields

Field	Type	Required	Description
`$schema`	String	No	Hosted schema URL for TOML-aware editors.
`version`	Integer	Yes	Settings format version. Currently `1`.

Environment

Field	Layer	Type	Description
`environment.variables`	Shared or local	Table of strings	Environment values passed to terminals, scripts, and agents.
`environment.secrets`	Local only	Table of strings	Secret values hidden after saving.
`environment.unset`	Local only	String array	Shared variable names to remove locally.

Local variables override shared variables by name. environment.unset removes the inherited value even when the shared file changes later.

Copied files

Field	Type	Default	Description
`files.include`	String array	`[]`	Gitignored file paths or patterns copied into new worktrees.

A local files.include list replaces the shared list. Radius copies regular files only and always excludes .radius/settings.local.toml.

Git

Field	Type	Default	Description
`git.base_ref`	String	Auto-detect	Starting ref for new worktrees.
`git.remote`	String	`origin`	Remote used for default push behavior and ref detection.
`git.delete_branch_on_archive`	Boolean	`false`	Delete a non-base local branch after successful archive.
`git.push_auto_setup_remote`	Boolean	`true`	Let a plain first push set the branch upstream.

Scripts

Field	Type	Default	Description
`scripts.startup`	String	Empty	Command run in a new project or worktree group’s terminal.
`scripts.setup`	String	Empty	Command run visibly after creating a worktree.
`scripts.archive`	String	Empty	Command that must succeed before removing a worktree.
`scripts.run.<id>`	Table	None	Named command shown in the terminal’s Run… menu.

Each named run command supports:

Field	Type	Description
`name`	String	Display name. Defaults to the script ID with separators replaced by spaces.
`command`	String	Shell command run from the active workspace.
`hide`	Boolean	Hide an inherited command. Use `true` in local settings.

Local override example

"$schema" = "https://radiusbrowser.com/schemas/settings.repo.schema.json"
version = 1

[environment]
unset = ["DEV_SERVER_PORT"]

[environment.variables]
DEV_SERVER_PORT = "5190"

[environment.secrets]
API_TOKEN = "local-secret"

[files]
include = [".env.local", ".npmrc.local"]

[scripts.run.dev]
hide = true

The Project Settings page edits local overrides. Open settings.toml from the page when you want to change shared repository behavior.

Get started

Guides

Cookbook

Reference

Advanced automation

Project settings

Settings file reference

Complete example

Root fields

Environment

Copied files

Git

Scripts

Local override example

​Complete example

​Root fields

​Environment

​Copied files

​Git

​Scripts

​Local override example

Complete example

Root fields

Environment

Copied files

Git

Scripts

Local override example