Module config 

forge.toml schema + loader.

Org model. Projects are grouped under [[orgs]] (Stargate, Gateway, Personal, etc.). Each org carries the accounts = [...] pin shared by all its projects, replacing the per-project pin that lived here before. Projects within an org keep a flat list via [[orgs.projects]]. A launch with no project named opens every project whose seat the store records as open, resuming the session forge stored for each unless --new is passed; the alphabetically first project is the fallback target when no project is named and no picker chooses one.

Selection policy. The gateway’s declared-model walk: over the org’s accounts primaries and fallback_accounts, the first account that declares the project’s model, preferring ready over saturated and keeping bailed last (saturated then leads to a cooling filter). Utilization is never compared between accounts; it collapses to one boolean per account. Every spawn in an org takes the same walk, so there is no per-session spread.

Re-exports

use std::collections::BTreeMap; 🔒

use std::collections::HashMap; 🔒

use std::fs; 🔒

use std::path::Path; 🔒

use std::path::PathBuf; 🔒

use std::time::Duration; 🔒

use forge_primitives::GotifyConfig; 🔒

use forge_primitives::account::Provider; 🔒

use forge_primitives::browser::ProfileKey; 🔒

use forge_primitives::permission::PermissionMode; 🔒

use forge_primitives::slack::SlackConfig; 🔒

use forge_primitives::ClientConfig; 🔒

use forge_primitives::ServerConfig; 🔒

use serde::Deserialize; 🔒

use serde::Deserialize; 🔒

use crate::error::WorkspaceError; 🔒

Structs

AccountEntry 🔒

Unknown fields are rejected so a near-miss key (providers) fails loudly instead of loading and leaving the account probing the wrong endpoint until preflight hangs on it.

BrowserSettings

The [browser] table: how the server’s browser hosts encode, and when an idle profile closes. Unknown fields are rejected so a mistyped key fails the load instead of being ignored.

ConfigReload

What one forge.toml reload changed, in the terms the boot’s log line reads: the tables whose new values are live from their next use, and the keys whose values are stored but need a restart.

DocumentsSettings 🔒

One [documents] table. Unknown fields are rejected so a mistyped key fails the load instead of being ignored.

ForgeToml 🔒

The whole forge.toml. Unknown keys are rejected so a mistyped section name fails the load instead of being ignored.

GatewaySettings 🔒

One [gateway] table. Unknown fields are rejected so a mistyped key fails the load instead of being ignored.

HandoffPolicy

The trigger a session reads, with the project’s table over the top-level one and the defaults under both.

HandoffSettings

The [handoff] table, top-level or per project. Every key is optional so a project’s table can set the one it disagrees on and inherit the rest.

HuggingfaceSettings

[huggingface]: the token a gated Hub repository needs. The speaking model’s own repository is open, so an absent token changes nothing.

LoadedAccount 🔒

One account as the config load produces it. The gateway’s account state is built from these, and the spawn path stamps the per-account env onto the child from here.

LoadedConfig 🔒

LoadedProject 🔒

ModelSettings

The [models."<name>"] table: the parameters a model name carries to every spawn, keyed by the canonical name forge.toml already pins projects to. Model-shaped values live here rather than in code, so changing a model is a config edit. Unknown fields are rejected so a mistyped key cannot silently leave a parameter unset.

OrgEntry 🔒

One [[orgs]] entry. Unknown keys are rejected: a misspelled fallback_accounts parses clean as “no fallbacks” otherwise, which is a silent behaviour change from a typo.

PluginSettings

The [plugins] section. Unknown fields are rejected so a mistyped key cannot silently leave auto-update doing nothing.

ProjectEntry 🔒

SessionsConfig

The validated [sessions] table: whether a dead durable seat comes back, how many restarts it gets, the wait before each, and how long a restarted seat must stay up before its count resets.

SessionsSection 🔒

One [sessions] table. Unknown fields are rejected so a mistyped key fails the load instead of being ignored.

SlackBinding 🔒

[orgs.slack] or [orgs.projects.slack]: the one [[slack]] label a scope’s sessions act in.

TerminalSettings

The [terminal] table: the shell a seat’s terminal runs, how much scrollback the model keeps, and when an idle terminal closes. Unknown fields are rejected so a mistyped key fails the load instead of being ignored.

UsageSettings 🔒

One [usage] table. Unknown fields are rejected so a mistyped key fails the load instead of being ignored.

VaultConfig 🔒

The validated [vault] section.

VaultSection 🔒

Optional [vault] section: the Vaultwarden account the vault family talks to. Both url and email are required when the section is present; there is no built-in default, because forge.toml is the one source of truth for the account.

Constants

DEFAULT_DOCUMENT_MAX_MIB

The ceiling a handed document has to fit under when the [documents] max_size_mib key is absent, in MiB.

DEFAULT_GATEWAY_PORT

The port the gateway’s listener binds when [gateway] port is absent. Fixed, not OS-assigned: every session’s base URL names it, so a drift would point children at an address nothing serves.

DEFAULT_HANDOFF_AFTER_COMPACTIONS

The compaction count the backstop hands off at when the key is absent. One is the first compaction: the fill trigger should have fired before it, and a session that reaches two is the alarm the record exists for.

DEFAULT_HANDOFF_AT_PERCENT

The share of the window a session hands off at when the key is absent.

DEFAULT_HEAL

Whether a dead durable seat comes back when [sessions] heal is absent.

DEFAULT_HEAL_ATTEMPTS

The restart count when [sessions] heal_attempts is absent: three restarts, which caps what a deterministic fault can burn.

DEFAULT_HEAL_BACKOFF_SECONDS

The waits before each restart when [sessions] heal_backoff is absent, in seconds: 5 s, 30 s, then 2 min.

DEFAULT_HEAL_STABLE_SECONDS

How long a restarted seat must stay up before its death count resets when [sessions] heal_stable is absent, in seconds.

DEFAULT_MAX_WORKERS_PER_PROJECT 🔒

Cap on a project’s concurrently live dynamic workers when its max_workers override is absent.

DEFAULT_USAGE_POLL_SECONDS

The interval the background usage poller refreshes on when the [usage] poll_seconds key is absent, in seconds. 60 s stays clear of the OAuth usage endpoint’s 429 throttle under multi-instance polling while bounding how stale the account-usage cache can be.

DOCUMENT_MAX_MIB_LIMIT

The highest [documents] max_size_mib forge accepts, in MiB. A document crosses the socket base64-encoded, a third larger, and the desktop client’s frame cap is 256 MiB (client/src-tauri’s MAX_FRAME_BYTES): 190 MiB raw lands at ~253.3 MiB, inside the cap with room for the answer’s other fields.

Functions

applied_env_keys 🔒

Sorted key NAMES a project contributes - never values; these tables hold tokens.

default_terminal_shell 🔒

The shell a terminal runs when [terminal] shell names none: the person’s own $SHELL, or the platform’s login shell.

ensure_forge_data_dir 🔒

forge_data_dir with a create_dir_all, returning the path.

expand_home 🔒

fingerprint_of 🔒

A stable 64-bit fingerprint of the file’s raw text, in hex. The settings page carries the fingerprint it loaded and a save is refused when the file has moved since.

forge_data_dir 🔒

The subdirectory holding every file forge itself owns (config, state, cron, lock), kept apart from claude’s own top-level config-dir files. Pure path join; call ensure_forge_data_dir when the directory has to exist before writing into it.

format_session_duration 🔒

The file’s spelling of a resolved [sessions] duration, for the settings page: the largest unit that divides it exactly.

is_bare_key_char 🔒

A TOML bare-key character (a-z A-Z 0-9 _ - .).

load_from_dir 🔒

Load + validate forge.toml. Returns the parsed orgs + projects with ~ expanded.

load_from_text 🔒

Load + validate raw forge.toml text, with the path its errors name. The settings save validates a candidate through here before it replaces the file, so the file a save writes is one a boot would accept.

parse_position 🔒

Where a parse failure sits in the document, from the byte span the error carries: at line N, column M in <key>, or empty when it names no span - no position rather than a confident line 1.

parse_session_duration 🔒

A [sessions] duration as the file writes it: digits and one unit, ms, s, m or h. A bare number is refused rather than guessed.

read_config 🔒

Read forge/forge.toml. Returns the path read plus its raw contents.

read_env_file 🔒

Parse KEY=value lines, skipping blanks and # comments. Every way this can go wrong warns and yields the keys it did read - a project’s env file is not worth refusing to boot over, and a partial read is visible in the per-spawn applied record’s key list.

resolve_client 🔒

The [client] section: an unset name is not an error and not a fallback, it means the built-in. A set one has to be a name forge ships, because a key that is quietly ignored reads as the key not working.

resolve_project_env 🔒

resolve_server 🔒

The [server] section, refusing the two ports that cannot work: 0, which is OS-assigned and so unguessable, and the gateway’s own port, where the listener that binds second loses at boot.

scrub_quoted 🔒

The error’s own words with any double-quoted run scrubbed: serde renders a mismatched value as invalid type: string "…", and a value in this file can be a token (#2267). A key is backtick-quoted and stays legible.

seat_env 🔒

A seat’s children’s environment: the server’s own first, then the account and project tables over it.

session_env 🔒

Complete [env] < [accounts.env] < the project’s env, narrowest winning per key, over the already-merged account_env. Applied here rather than at load because one account serves many projects, so merging earlier would leak a project’s keys into every other project on that account.

slack_binding_label 🔒

The label a scope’s slack binding resolves to, or a load error naming the label asked for and the ones that exist: a binding to a workspace forge does not have would leave every Slack tool dead at runtime.

trim_setup_token 🔒

A project’s env: the env_file entries with the inline env table layered over them, since the inline form is the more explicit statement of the two. Trim the setup token a project’s env declares: the spawned child reads that map verbatim, so a padded value would fail to authenticate. The account layers never reach here with one - the load drops the gateway keys before they merge.

validate_handoff_settings 🔒

Refuse a trigger that can never fire or fires on every turn. scope names the table the value came from, so the error says which one to edit.