Every FlightDeck configuration key, its default, and what it does. For how the
global and project files layer together and the in-app editor, see
Configuration .
~/.flightdeck/config.toml # per-user GLOBAL base (all keys, documented)
<repo>/.flightdeck/config.toml # per-project OVERRIDE (only changed values)
Project identity — lives in the project file only.
Key Default Meaning namerepo folder name Project display name default_base_branchdetected / main Base branch for new tabs
Key Default Meaning root.flightdeck/worktreesWhere managed worktrees are created
Key Default Meaning default_remoteoriginRemote to push to primary_hostgithubHost used to build the PR compare URL branch_prefixflightdeck/Prefix for generated branch names
Key Default Meaning agent_tab_positionleftSidebar on the left or right default_agentopencodeAgent key selected by default for new tabs use_f2_to_leave_terminal_focusfalseUse F2 instead of modified Esc to leave terminal focus macos_option_as_metafalseDesktop app on macOS only: send unbound Option+key as Esc+key (Meta) instead of the composed character. No effect on Linux, Windows or in the TUI desktop_terminal_font_size13Desktop app only: terminal text size in points, 8 to 32. On macOS Cmd-= / Cmd-- zoom for the session and Cmd-0 resets file_manager"" (per-OS default)Command used by Open Worktree in File Manager ; empty means open / explorer.exe / xdg-open
See Notifications .
Key Default Meaning enabledtrueMaster switch on_finishtrueNotify when an agent goes idle / completes on_waitingtrueNotify when an agent needs input on_failedtrueNotify when an agent errors soundtruePlay alert sounds
Key Default Meaning checktrueDaily background update-availability check
FlightDeck Remote (phone pairing). See FlightDeck Remote .
Key Default Meaning enabledfalseMaster switch for phone pairing relay_urlwss://relay.flightdeckai.app/wsRelay WebSocket URL (empty disables) push_done_debounce_secs5Seconds an agent must stay idle after a turn before your phone gets a "done" push. Going back to work inside the window cancels it, so mid-turn pauses don't notify. 0 pushes immediately; at most 3600. Needs-input and error pushes are never delayed
warning The default relay_url (relay.flightdeckai.app) is restricted and not
accessible to the public — enabling Remote against it will not connect. You
may set relay_url to a relay you host yourself, but self-hosting is not
supported by the author. See FlightDeck Remote → Availability .
Both enabled and relay_url can also be edited in the in-app configuration
manager.
FlightDeck Web (the browser control surface). See FlightDeck Web .
Key Default Meaning enabledfalseAuto-start the web server on launch. Off by default — starting it is otherwise an explicit palette action port7420TCP port the embedded server listens on. A configured 0 is rejected bind127.0.0.1Bind address. Loopback by default; a routable address is an explicit opt-in replay_bytes262144Per-terminal replay ring buffer, in bytes (256 KiB). Bytes rather than lines, because the buffer sits in front of the VT parser
warning Setting bind to a routable address (0.0.0.0, or a LAN interface IP) makes
FlightDeck reachable from your network, and anyone there holding an access
code can type into your agents and push branches. FlightDeck warns when the
server actually starts on such a bind. Never expose it directly to the public
internet — use Tailscale or ssh -L instead. See
Access & Security .
FlightDeck Worker (headless host controlled from Desktop or a browser). Global config only. See
Run a FlightDeck Worker .
Key Default Meaning port7420TCP port served on each Tailscale address. A configured 0 is rejected projects_root"~/flightdeck"Scanned two levels deep for repositories to offer; clones land here default_cols200Terminal width when no window has reported a size (20–1000) default_rows50Terminal height when no window has reported a size (4–500) phonefalseLet the FlightDeck iPhone app pair with this worker webtrueServe FlightDeck Web's page, so a browser can pair and drive the worker httpstrueFetch a Tailscale certificate and answer HTTPS on the same port (only when the tailnet has HTTPS certificates on)
Run agents in Podman containers. See Agents in Containers .
Key Default Meaning enabledfalseRun all of the project's agents in containers runtimepodmanContainer runtime (only Podman is supported) image— Fully-resolved image override base_image— Override the generated base image packages[]OS packages to install into the image setup_script— Repo-relative build script containerfile— Bring-your-own Containerfile (mutually exclusive with packages / setup_script) forward_ports[]Ports published to 127.0.0.1 only
Key Default Meaning cpu4--cpusmemory8g--memorypids512--pids-limit
Key Default Meaning env_allow[]Host environment variables injected into the container
An array of credential mounts, each with:
Key Meaning host_pathPath on the host to mount container_pathWhere it appears in the container writableWhether the mount is writable
One table per agent. A project that defines any agent replaces the agents
table wholesale (see Configuration ).
Key Meaning display_nameName shown in menus commandExecutable to launch (must be on PATH) argsArguments passed to the command
[agents.claude]
display_name = "Claude Code"
command = "claude"
args = []
FlightDeck rejects invalid configs at load time: an empty agents map, a
default_agent that isn't a defined agent, an agent with an empty command, an
unsupported container runtime (when containers are enabled), a containerfile
combined with packages/setup_script, and zero or duplicate forward_ports.
Previous: Keyboard Shortcuts Next: Troubleshooting