Server, settings and config
fontego-server's commands, the settings an admin can change, and every key of the config file.
fontego-server
The server's own program: it runs the server and sets it up on the machine where it runs. Every command works
without questions, so a script or an agent can install Fontego from start to finish. In the container it is
docker compose exec server fontego-server ....
fontego-server 0.1.0
Usage: fontego-server <command> [options]
serve Run the server (FONTEGO_HOST, FONTEGO_PORT, FONTEGO_DATA_DIR, FONTEGO_CONFIG)
init EMAIL [options] First run, without questions: the server admin and a link to set their
password, the visible name and the first workspace. Each option can go in
[init] of the config file instead; running it again changes nothing that is there
--admin-name NAME The admin's name
--display-name NAME The name the web app shows (an admin can change it later)
--token Also a token for the CLI, shown once
--workspace SLUG The first workspace, with the admin as its admin, filled from one of:
(nothing) empty
--template NAME a template (fontego-server templates)
--from PATH a folder or a .zip on this machine
--git URL|PATH [--branch B] a Git repository, with its history (--no-history: only its last version)
--workspace-name NAME, --workspace-description TEXT, --workspace-category C
admin-link EMAIL A link to set someone's password, for when nobody can sign in or there is
no mail (it resets the password of an account that has one)
user add EMAIL [--name NAME] [--admin] Create an account without a password (to invite people: fontego admin users invite)
user list
token create EMAIL [--label L] [--agent] Print a new token for that person (or for their agent)
token list EMAIL
token revoke ID
workspace create SLUG [--name N] [--description D] [--category C] [--owner EMAIL]
[--template NAME | --from PATH | --git URL|PATH [--branch B] [--no-history]]
The owner (default: the first server admin) becomes its admin
workspace list
templates The templates a workspace can start from
member set SLUG EMAIL ROLE ROLE: reader | editor | admin
member remove SLUG EMAIL
doctor [--mail-to EMAIL] [--strict] What works and what production still needs: git, the data folder and its
permissions, the admin, the public URL and its HTTPS, mail, backups.
Exits 1 if something fails (--strict: or needs attention)
Add --json to get machine-readable output.Settings
What a server admin can change while the server runs, from the web or with
fontego admin settings set. Each value comes from the first place
that has it: the server's config (the variable, or the key in the config file), which pins it; what an admin set;
or the default.
| Setting | Type | Default | Pinned by | |
|---|---|---|---|---|
displayName | string | Fontego | FONTEGO_DISPLAY_NAME, or displayName | Name people see in the web app and in mail. |
smtp.host | string | none | FONTEGO_SMTP_HOST, or host in [smtp] | SMTP server. Without one, mail waits for an admin to pass it on. |
smtp.port | number | 587 | FONTEGO_SMTP_PORT, or port in [smtp] | SMTP port. |
smtp.secure | boolean | none | FONTEGO_SMTP_SECURE, or secure in [smtp] | TLS from the start; otherwise STARTTLS when the server offers it. Unset: on for port 465. |
smtp.user | string | none | FONTEGO_SMTP_USER, or user in [smtp] | SMTP user, if the server asks for one. |
smtp.password | string | none | FONTEGO_SMTP_PASSWORD, or password in [smtp] | SMTP password. It can be set, never read back. FONTEGO_SMTP_PASSWORD_FILE keeps it out of the database. |
smtp.from | string | none | FONTEGO_SMTP_FROM, or from in [smtp] | Sender of every message: an address, or "Name <address>". |
sessions.web.idleDays | number | 30 | FONTEGO_SESSIONS_WEB_IDLE_DAYS, or idleDays in [sessions.web] | Browser sessions: days unused before they end (applies at once to open sessions). |
sessions.web.maxDays | number | 90 | FONTEGO_SESSIONS_WEB_MAX_DAYS, or maxDays in [sessions.web] | Browser sessions: days at most from when they open (lowering it shortens open sessions too). |
sessions.cli.idleDays | number | 30 | FONTEGO_SESSIONS_CLI_IDLE_DAYS, or idleDays in [sessions.cli] | CLI sessions: days unused before they end (applies at once to open sessions). |
sessions.cli.maxDays | number | 90 | FONTEGO_SESSIONS_CLI_MAX_DAYS, or maxDays in [sessions.cli] | CLI sessions: days at most from when they open (lowering it shortens open sessions too). |
paths.protected | list | **/AGENTS.md, **/CLAUDE.md, **/.agents/**, **/.claude/**, **/.github/copilot-instructions.md, **/.github/instructions/**, **/.opencode/**, **/.cursor/rules/** | FONTEGO_PATHS_PROTECTED, or protected in [paths] | Paths only a workspace's admins can change, for workspaces without their own list (fontego workspace paths). |
paths.rejected | list | **/.claude/settings*.json, **/.mcp.json, **/.vscode/mcp.json, **/.cursor/mcp.json, **/opencode.json, **/opencode.jsonc, **/.opencode/plugin/**, **/.opencode/plugins/** | FONTEGO_PATHS_REJECTED, or rejected in [paths] | Paths nobody can write, because those files would run code on the machines of everyone who syncs, for workspaces without their own list. |
The config file
Every key, commented. Point FONTEGO_CONFIG at the file; a FONTEGO_* variable wins over the same key here. How
the layers fit together is in Configuration.
# A config file for fontego-server: point FONTEGO_CONFIG at it. Everything is optional, and a FONTEGO_* variable
# wins over the same key here. One file can describe a whole install: how the server runs (the top, read at every
# start) and what `fontego-server init` sets up the first time ([init], read only by init).
# --- How the server runs (a restart applies a change) ---
host = "127.0.0.1" # FONTEGO_HOST; 0.0.0.0 in the container
port = 8740 # FONTEGO_PORT
dataDir = "/var/lib/fontego" # FONTEGO_DATA_DIR: every workspace and the database; only the server's user may enter it
publicUrl = "https://fontego.example.org" # FONTEGO_PUBLIC_URL: the address people and their CLIs use, behind a proxy with HTTPS
# templatesDir = "/etc/fontego/templates" # FONTEGO_TEMPLATES_DIR: this instance's own templates, one folder each
# clientIpHeader = "cf-connecting-ip" # FONTEGO_CLIENT_IP_HEADER: the header the proxy in front puts the caller's
# address in (x-real-ip for nginx). Set it behind a proxy, or every caller
# shares the proxy's address and its limits; only if all traffic comes through it
[storage]
type = "disk" # FONTEGO_STORAGE; "s3" will come, with its bucket and endpoint here
[identity]
type = "local" # FONTEGO_IDENTITY: accounts with a password; "oidc" will come
[policy]
maxFileBytes = 20971520 # FONTEGO_MAX_FILE_BYTES
blockSecrets = true # FONTEGO_BLOCK_SECRETS
# [import]
# privateNetworks = false # FONTEGO_IMPORT_PRIVATE_NETWORKS: let a Git import through the API reach
# private addresses (this machine, its networks, a VPN). Off: public only
# Backups are the deployment's business. Have the backup job touch this file when it succeeds, and
# fontego-server doctor says how old the last one is.
# [backups]
# stamp = "/var/lib/fontego-backup/last-success" # FONTEGO_BACKUP_STAMP
# maxAgeHours = 36 # FONTEGO_BACKUP_MAX_AGE_HOURS
# --- Settings an admin could change while it runs: set here, they are pinned and win ---
# displayName = "Fontego" # FONTEGO_DISPLAY_NAME; to only start with a name, use [init] instead
# [smtp]
# host = "smtp.example.org" # FONTEGO_SMTP_HOST, _PORT, _SECURE, _USER, _FROM
# port = 587
# user = "fontego@example.org"
# passwordFile = "/run/secrets/smtp_password" # FONTEGO_SMTP_PASSWORD_FILE
# from = "Fontego <fontego@example.org>"
# [sessions.web]
# idleDays = 30
# maxDays = 90
# --- The first run: fontego-server init (options on its command line win) ---
[init]
admin = "you@example.org" # init EMAIL: the server admin, who gets a link to choose a password
# adminName = "Your Name" # --admin-name
# displayName = "Our team" # --display-name: the name to start with; an admin can change it later
# token = true # --token: also a token for the CLI, shown once
[init.workspace] # --workspace SLUG: the first workspace, with the admin as its admin
slug = "notes"
# name = "Notes"
template = "demo" # --template NAME, or one of:
# from = "/srv/import/notes" # --from: a folder or a .zip on this machine
# git = "https://example.org/notes.git" # --git: a Git URL or a repository on this machine, with its history
# branch = "main" # --branch
# history = false # --no-history: only its last version