Switchboard has Global Settings (the gear in the sidebar's tab row) and
Project Settings (the gear on a project header). Settings are stored in
Switchboard's SQLite database (switchboard.db in the data directory), in the
settings table: key global, and project:<path> per project.
A value is resolved in this order: the project's value if it overrides one, the
global value if one was ever saved, the built-in default otherwise
(public/setting-defaults.js). Most settings apply on Save Settings; two
switches, marked live below, apply the moment they are flipped.
The pages are General, Sessions, Keyboard, Automation, Remote hosts, Integrations, Archived and Advanced. Project Settings has Launch and This project. Each scope remembers its last page on this computer. A narrow viewer automatically places the navigation in a horizontal strip above the page. See Settings navigation for the keys.
All pages share one Save: switching pages keeps edits, and the footer counts unsaved changes. Save keeps Settings open and flashes Saved; Cancel discards edits without asking. Live switches and Unarchive still take effect immediately.
Startup, Shell, Terminal and IDE settings:
| Setting | Key | Default | Effect |
|---|---|---|---|
| Terminal Theme | terminalTheme |
Switchboard | Terminal colours, applied on save — see Terminal |
| Terminal Right-Click | terminalRightClick |
Context menu (menu) |
menu, paste, default (Native), none — see Terminal |
| Restore Sessions on Startup | restoreOnStartup |
Ask on startup (ask) |
off, ask, lazy (Restore on click), auto; read at launch — see Session restore |
| Shell Profile | shellProfile |
Auto (detect) | The shell for sessions and terminals; new sessions only — see Launching sessions |
| IDE Emulation | mcpEmulation |
off | Switchboard as Claude's IDE; new sessions only — see IDE emulation |
| Setting | Key | Default | Effect |
|---|---|---|---|
| Automatic Updates | autoUpdate |
on | Download updates in the background and install them when Switchboard quits; read at launch |
| Receive beta versions | receiveBetaVersions |
off | Include GitHub pre-releases in automatic and manual update checks; applied at launch and on Save Settings |
| Version | — | — | The installed version and the update status |
| Check for Updates | — | — | Checks GitHub Releases now |
An installed build with Automatic Updates on checks GitHub Releases 5 seconds after launch and every 4 hours. A downloaded update brings a bar, Update ready — restart to apply, with Restart and Later; Later hides it for that version, and the update installs at the next quit.
With Automatic Updates off, Switchboard never fetches or replaces its own binary on its own: nothing is checked until you press Check for Updates, which then downloads the update found, and it installs when you choose to restart. This keeps a locally built or patched build in place; with it on, the next release of the same or a higher version replaces it at quit.
Builds run from source never check.
Stable is the default channel. Turn on Receive beta versions and click Save Settings to include beta releases in future update checks. The same binary serves both channels; the release's GitHub pre-release status decides whether it is beta. Turning the switch off never downgrades: an installed beta stays in place until a newer stable version is available. A beta that was already downloaded before you turned the switch off still installs at the next quit. The SQLite cache only migrates forward.
These are the defaults for new sessions; the New Session dialog can change them for one launch — see Launching sessions.
| Setting | Key | Default | Effect |
|---|---|---|---|
| Permission Mode | permissionMode |
auto until a value is saved |
--permission-mode; Default (none) passes no flag — see permission modes |
| Worktree | worktree |
off | Starts new sessions with --worktree — see Worktree sessions |
| Worktree Name | worktreeName |
empty (auto) |
The name passed after --worktree |
| Browser | browserMode |
Off (off) |
Off passes no browser flag; Claude in Chrome (claude-in-chrome) passes --chrome |
| Sandbox (Linux only) | sandbox |
off | Runs claude under bubblewrap — see Sandbox |
| Additional Directories | addDirs |
empty | Comma-separated; one --add-dir each |
A saved chrome setting is read as the matching Browser choice: true selects
Claude in Chrome, and false selects Off.
| Setting | Key | Default | Effect |
|---|---|---|---|
| Pre-launch Command | preLaunchCmd |
empty | Written in front of the claude command, e.g. aws-vault exec profile --; restricted to letters, digits, spaces and - _ . / \ : = — see Launching sessions |
The existing CLI switches and Codex sandbox, approval, model and reasoning-effort controls are grouped here. See Launching sessions.
Show Codex usage (showCodexUsage, off by default) displays Codex rate
limits in the status bar and Stats. When enabled, it reads CODEX_HOME/auth.json
(or ~/.codex/auth.json) and calls chatgpt.com with the Codex login token
and, when present, the account id in the chatgpt-account-id header.
Unavailable credentials, request failures or unsupported responses hide the
Codex gauges quietly. Saving a changed toggle applies it immediately.
| Setting | Key | Default | Effect |
|---|---|---|---|
| Max Visible Sessions | visibleSessionCount |
10 (1–100) | Sessions shown per project before + N older |
| Session Max Age (days) | sessionMaxAgeDays |
3 (1–365) | Older sessions go behind + N older; older projects start collapsed |
| Hide SDK-launched Sessions | hideSdkSessions |
on | Leaves out of the sidebar and grid the sessions a program started: Claude Agent SDK runs and non-interactive codex exec runs; scheduled tasks stay — see Session browser |
Eight rebindable shortcuts, stored as shortcuts: Toggle Changes, Show
pending Diff, Toggle Touched, Toggle Shell, Navigate sessions / grid, Previous /
next session, Toggle grid view and Toggle agents view. Each defaults to
Primary+Shift (Ctrl, or Cmd on macOS) with its key — see
Keyboard shortcuts for the keys and
Rebinding.
| Setting | Key | Default | Effect |
|---|---|---|---|
| Schedules tab | schedulesTab |
off | Moves project schedule files from Agent Files to the Schedules tab on save; while off, the files and Run now stay in Agent Files — see Automation |
| Setting | Key | Default | Effect |
|---|---|---|---|
| SSH hosts to observe | remoteHosts |
none | {alias, label, enabled} per host — see Remote hosts |
| Refresh every | remoteRefreshMs |
5 minutes (minimum 1; the field offers up to 1440) | Time between full pulls |
| Setting | Key | Default | Effect |
|---|---|---|---|
| Send session activity to ActivityWatch | activityReporting |
off | Live. Reports session time to a local ActivityWatch — see ActivityWatch |
The What is sent explanation expands when selected.
Project and folder archives are grouped by host, with Local first. Each row shows its name, full path (also in the tooltip), Project or Folder badges (both when archived both ways), any legacy badge, and the available archive date. Folder archives also show how many schedules the archive turned off. Worktree entries keep their own rows and paths. Filter by name, path, host label or alias; Escape clears the filter. Host headers fold with Enter or Space. Select rows or a host group to unarchive several projects together.
Unarchive applies immediately. Project restores offer a ten-second Undo; folder restores keep sessions archived and schedules off, with Turn back on offered at the top of the restored group. Re-archive a folder with Archive folder; in a mixed restore, Undo re-archives projects only. A combined row restores its project archive first, then its folder archive. The row's More actions menu offers Copy path and Delete project…. Delete opens the same preview and confirmation as the sidebar, without unarchiving first. Archived session management will be added separately.
| Setting | Key | Default | Effect |
|---|---|---|---|
| Debug Mode | activityTrace |
off | Live. Records the activity trace; lists, opens and deletes trace files — see Activity trace |
The What it records explanation expands when selected.
sidebarWidth(default 340): the sidebar's width, set by dragging its edge.hiddenProjects: projects archived with Archive Project, including legacy hidden entries, and projects deleted from Switchboard (kept out of the sidebar; not listed in Archived projects).hiddenProjectKindsrecords which is which.hiddenProjectArchivedAt: archive timestamps keyed by the exact hidden entry; older entries without a timestamp display no date.archivedProjects, a setting of its own: folders hidden with Archive folder, each with the session ids it held and the schedule files it disabled.scheduleReenableOffers, a setting of its own: for each folder that came back, the schedules its archive disabled, until Turn back on or Dismiss.openWorkingSet: the open sessions, for session restore.dangerouslySkipPermissions(default off): launches with--dangerously-skip-permissions; no settings field sets it, the dialogs' Dangerous Skip applies to one launch.remoteTriggers(default off): lets a trigger reach a session of an enabled remote host — see Automation.lastSeenVersion(default none): the last version whose What's new was shown — see Changelog.
Project Settings override, for one project, the fields on the Launch page: Permission Mode, Worktree, Worktree Name, Browser, Sandbox (Linux only), Additional Directories and Pre-launch Command. Each field has a Use global default box; while it is checked the field shows the global value and nothing is stored for the project.
The This project page shows the project's name, full path, host, folder key and the number of sessions, including archived ones. Counts are unavailable when the project is absent from the current project list. Its Danger zone holds Archive Project and Delete Project; the footer holds only Cancel and Save Settings. The first visit opens Launch; later visits remember the last project page.
Archive Project removes the project and its nested worktrees from the sidebar immediately, without asking. A notice offers Undo for about 10 seconds; it restores the project and resumes scheduling. Settings, cached sessions and search entries are kept. Schedules stay on disk with their enabled state unchanged, but Switchboard suspends their launches until you unarchive the project. Already running sessions and schedules continue.
In Global Settings → Archived, Unarchive restores the sidebar row and resumes scheduling (a run that fell due while archived is not replayed); Add Project on the same local folder also restores it. Previously hidden projects appear here too, with default settings because the old Hide action already removed their settings. A remote entry includes its host alias; unarchiving it does not register a local schedule.
Delete Project opens the same preview as Delete on the project header. Choose whether to discard session names, pins and app metadata (initially off) and project settings (initially on when available). Unselected session metadata is archived. Shared path-only settings cannot be deleted. Only confirmed, available choices are remembered; Cancel changes nothing.
The preview shows the full host and path, counts, and expandable complete
targets and effects. Project files, transcripts, schedules, memory, .work-files
and nested worktrees stay on disk. Kept schedules may reactivate on re-add;
retained transcripts can restore their titles. Background jobs must be stopped
from the Agents view first. Local terminal stopping for deletion requires Windows;
on other platforms stop the terminals first and reopen the preview.
An unresolved deletion offers Check deletion state, without replaying it. A partial result offers Review remaining deletion for a fresh preview. If recovery is unavailable, deletion is unavailable for all projects until it finishes; reopen Delete or check the announced operation to retry. A completed deletion whose views failed to refresh offers Reload window.
Project Archive stays in effect until restored explicitly. It differs from Archive folder, which returns on new activity and can optionally archive sessions and disable schedule files.
| Variable | Effect |
|---|---|
SWITCHBOARD_DATA_DIR |
Data directory: database, trace files, remote mirrors, and Electron's userData (hence its own single-instance lock). Default ~/.switchboard for an installed build, ~/.switchboard-dev from source. Set to any value, even ~/.switchboard, it turns schedule catch-up off — see Automation |
SWITCHBOARD_TRIGGERS_DIR |
Triggers directory, default ~/.switchboard/triggers whatever the data directory — see Automation for the other trigger variables |
SWITCHBOARD_ACTIVITY_TRACE, SWITCHBOARD_ACTIVITY_TRACE_MAX_MB |
Debug mode at startup, and its disk ceiling — see Activity trace |
SWITCHBOARD_SSH_PATH |
The ssh binary of every remote operation: pulls (scp included, through scp -S), watch connection, attached terminal, stop, Changes view. An absolute path to an executable — a relative value is ignored, and a Windows .cmd/.bat cannot be started. Unset, ssh from the PATH, then the system's — see Remote hosts |
SWITCHBOARD_SCP_PATH |
The scp binary of the pulls, same rules. Unset, the scp beside SWITCHBOARD_SSH_PATH when there is one, then scp from the PATH, then the system's — see Remote hosts |
SWITCHBOARD_SANDBOX_DEBUG=1 |
Verbose sandbox launch, set through the Pre-launch Command — see Sandbox |
SWITCHBOARD_NO_CONPTY_DLL=1 |
Windows: use the system's ConPTY instead of the one bundled with node-pty |
SWITCHBOARD_TEST_CONCURRENCY |
Test runner workers — see Development |