Version: v3 (beta)

Config

TF Code uses JSON config files merged in precedence order. Profile credentials and environment variables override file-based settings.

Interactive Setup

The recommended way to get started:

tfcode setup

This prompts for profile name, workspace ID, API key, and region, then saves them as a named profile.

Profiles

Profiles store multiple sets of ToothFairyAI credentials so you can switch between workspaces instantly.

Create

tfcode setup
# Prompts for: profile name, workspace ID, API key, region

Non-interactive:

tfcode setup --profile dev --workspace-id dev-ws-456 --api-key dev-key-xxx --region dev --name dev

Switch

tfcode profile prod
tfcode profile
# Current profile: prod
#
# Available profiles:
#  *  prod
#     dev

Use in commands

tfcode -p prod run "Deploy to production"
TF_PROFILE=prod tfcode run "Force prod workspace"

Storage

Profiles are stored in ~/.local/share/tfcode/.tfcode/profiles.json:

{
  "default": "prod",
  "profiles": {
    "prod": {
      "api_key": "prod-key-xxx",
      "workspace_id": "prod-ws-123",
      "region": "au"
    },
    "dev": {
      "api_key": "dev-key-yyy",
      "workspace_id": "dev-ws-456",
      "region": "dev"
    }
  }
}

Profiles replace the legacy credentials.json. TF Code automatically migrates it on first profile command.

Regions

Region	Base URL	Streaming URL
`dev`	`ai.toothfairylab.link`	`ais.toothfairylab.link`
`au`	`ai.toothfairyai.com`	`ais.toothfairyai.com`
`eu`	`ai.eu.toothfairyai.com`	`ais.eu.toothfairyai.com`
`us`	`ai.us.toothfairyai.com`	`ais.us.toothfairyai.com`

Config File Locations

Config sources are loaded in order of increasing priority (later overrides earlier):

Global config — ~/.config/tfcode/tfcode.json
Custom config — OPENCODE_CONFIG env var path
Project config — tfcode.json in project root
.tfcode/tfcode.json in project root
Inline config — OPENCODE_CONFIG_CONTENT env var
Active profile — set via tfcode profile <name> or --profile / TF_PROFILE
Environment variables — TF_WORKSPACE_ID, TF_API_KEY, TF_REGION

Files are merged together, not replaced. Non-conflicting settings from all sources are preserved.

note

tfcode sync can replace the global config file with a workspace-managed tfcode.json published by your workspace admin — the previous file is kept as tfcode.json.bak. See Workspace Sync.

Project config example

.tfcode/tfcode.json:

{
  "toothfairy": {
    "workspace_id": "your-workspace-id",
    "api_key": "your-api-key",
    "region": "au"
  },
  "model": "toothfairyai/mystica",
  "default_agent": "build"
}

Feature config sections

Top-level config keys that switch on agent features (see Agents for details):

Key	Type	Description
`reviewer`	object	Stronger model agents call for second opinions (see Reviewer)
`model_swap`	object	Lets agents switch models mid-session (see Model swap)
`escalate`	object	Lets agents temporarily upgrade to a stronger model, matched on problem domain (see Escalate)
`loops`	object	Structured execution-path workflows (see Loops)
`kanban`	object	Kanban dispatcher — watches boards and runs ready tasks with agents (see Kanban)
`handoff`	object	Cloud hand-off tuning — delegate subagent tasks to a cloud runner under pressure (see Cloud Hand-off)
`tfdesign`	object	TF Design add-on — CLI path, daemon URL, and mirror directory (see TF Design)
`office`	object	Office documents — LibreOffice previews and desktop editing (see Office documents)
`policies`	array	Allow/deny rules for providers, tools, MCP, and skills (see Policies)
`self_improve_skills`	boolean \| object	Steers agents to refine their own skills. Supports `enabled_for`, `validate`, `history_dir`, and reserved `embeddings` (see Self-improving skills)
`perks`	object	Named capabilities (e.g. `computer-use`, `voice`, `mailbox`) whose default on/off state applies to every new session — seeds session toggles (see Perks)
`settings`	object	Web app preferences — general, appearance, keybinds, permissions, notifications, sounds, voice, theme (see Web app settings)

Perks

Perks are the single gate for every capability — built-in plugins (email, scheduler, vibeguard, goal, loops, notifications, gateway) and on-demand session capabilities alike. Set a perk's default state once and it applies to every new session:

{
  "perks": {
    "computer-use": true,
    "voice": true,
    "scheduler": true,
    "plugins": true
  }
}

Each perk key is a boolean:

Key	Description
`"computer-use"`	Default state of the computer-use perk (OS GUI control) for new sessions — users can still toggle it per session via the UI icon
`"voice"`	Default state of the voice perk (mic input, spoken callouts, TTS) for new sessions
`"delegate_on_cloud"`	Enables cloud hand-off — delegate subagent tasks to a cloud runner when local resources are under pressure (see Cloud Hand-off)
`"escalate"`	Enables the escalate perk — agents may temporarily upgrade to a stronger model, matched on the problem's domain via benchmark data (see Escalate)
`"mailbox"`	Enables the mailbox perk — auto-connects the built-in mailbox MCP server for email/calendar access (see Mailbox)
`"scheduler"`	Enables the scheduler — recurring jobs and routines on a schedule (see Scheduling)
`"email"`	Enables the `send_email` tool — premium branded HTML email through the ToothFairyAI SES pipeline
`"vibeguard"`	Enables Vibeguard — secrets/PII redacted into placeholders before LLM calls
`"goal"`	Enables the `/goal` command — session objective tracking with auto-continue
`"loops"`	Enables structured step-by-step loop workflows (see Loops)
`"notifications"`	Enables desktop alerts and sounds when a session finishes or permission is requested
`"gateway"`	Enables the webhook receiver gateway (see Gateway)
`"browser"`	Unattended browsing without per-action permission asks (the `browser` tool)
`"session_search"`	Enables the `sessions` tool — read other sessions of this project
`"plugins"`	Enables agent plugins — self-authored, declarative plugin manifests in `.tfcode/plugin/` (see Plugins)

Absent perks default to off.

note

The old builtin config ("builtin": { "scheduler": { "enabled": true } }) still works as a read-only fallback — perks.<name> always wins when set. All new writes (via the plugin_recommend tool, the /plugins toggle, or the HTTP API) go to perks.*.

You normally don't edit this by hand: ask the agent about capabilities ("what plugins should I turn on?") and it uses the plugin_recommend tool to list, recommend, and toggle them — with your confirmation before anything changes.

Mailbox

The mailbox perk auto-connects the built-in mailbox MCP server (tf-mailbox) — a zero-install, stdio server that gives agents read access to the user's email and calendar. No API keys or extra setup: it reads from the local mail store and exposes tools like list_folders, list_emails, read_email, and calendar queries. Enable it once and every new session has the tools available:

{
  "perks": {
    "mailbox": true
  }
}

Web app settings

The settings section stores web app preferences. It is applied on the next UI load and validated against the real catalogs (themes, sounds, fonts, keybinds) — invalid values are dropped with a warning. Agents can read and update it at runtime via the tfcode_config tool.

{
  "settings": {
    "general": { "autoSave": true, "followup": "queue" },
    "appearance": { "font": "intel-one-mono", "fontSize": 14 },
    "theme": { "colorScheme": "system" },
    "permissions": { "autoApprove": false },
    "notifications": { "agent": true, "permissions": true, "errors": true },
    "sounds": { "agentEnabled": true },
    "voice": { "ttsModel": "cartesia" }
  }
}

Key	Description
`general`	Auto-save, release notes, follow-up handling (`queue`/`steer`), reasoning/thinking display, tool part expansion, computer-use and voice toggle defaults
`updates`	Check for app updates on startup
`appearance`	Chat font size and monospace font id
`keybinds`	Keybind overrides for the web app, keyed by action name
`permissions`	Auto-approve permission requests in the web app
`notifications`	Notify when the agent finishes, a permission is requested, or on errors
`sounds`	Sound on/off and sound id for agent finish, permission request, and errors
`voice`	TTS model, voice, language, and auto-send for voice transcriptions
`theme`	Theme id and color scheme (`light`/`dark`/`system`) applied at startup

note

Agent-level perks are a different concept: setting perk: "tf_engineer" or perk: "tf_orchestrate" on an agent definition makes it inherit the full behaviour of the native ToothFairyAI agent (prompt, permissions, MCP and TF tool access). See Agent perks.

Environment Variables

Variable	Description
`TF_WORKSPACE_ID`	ToothFairyAI workspace ID
`TF_API_KEY`	ToothFairyAI API key
`TF_REGION`	ToothFairyAI region: dev, au, eu, us
`TF_PROFILE`	Profile name to use (overrides default profile)
`TFCODE_SERVER_PASSWORD`	HTTP basic auth password for server mode
`TFCODE_SERVER_USERNAME`	HTTP basic auth username (default: tfcode)
`OPENCODE_CONFIG`	Path to custom config file
`OPENCODE_CONFIG_CONTENT`	Inline config content (highest priority)

Validate

tfcode validate
tfcode validate --profile prod

Server Config

The server block controls the HTTP server:

{
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1",
    "mdns": false,
    "mdnsDomain": "tfcode.local",
    "cors": ["https://app.example.com"]
  }
}

Logging

tail -f ~/.local/share/tfcode/log/dev.log
tfcode --log-level DEBUG

Levels: DEBUG, INFO, WARN, ERROR.

CLI Commands Reference

Top-level

Command	Description
`tfcode`	Start interactive session
`tfcode run <prompt>`	Execute a single task and exit
`tfcode serve`	Start headless HTTP server
`tfcode web`	Start server and open web interface
`tfcode attach <url>`	Attach TUI to a running server

Setup & credentials

Command	Description
`tfcode setup`	Interactive credential setup (creates a profile)
`tfcode validate`	Validate credentials (`--profile <name>` for specific)
`tfcode profile`	Show current profile and list all
`tfcode profile <name>`	Switch to a different profile
`tfcode sync`	Sync workspace tools metadata
`tfcode policy`	List local and workspace policy statements
`tfcode providers list`	List available providers
`tfcode models [provider]`	List available models (optional provider filter)
`tfcode models --verbose`	List models with metadata
`tfcode models --refresh`	Refresh the models cache

MCP

Command	Description
`tfcode mcp list`	List MCP servers and tools
`tfcode mcp add`	Add a local MCP server
`tfcode mcp auth`	Authenticate with OAuth MCP server
`tfcode mcp logout`	Logout from MCP server

Other

Command	Description
`tfcode -p/--profile`	Switch profile per command
`tfcode --log-level`	Set log level
`tfcode --version`	Show version
`tfcode --help`	Show all commands
`tfcode gateway`	Manage webhook subscriptions

Chat commands (interactive)

Command	Description
`/compact [instructions]`	Compact context with preservation hints
`/help`	Show available commands

Interactive Setup​

Profiles​

Create​

Switch​

Use in commands​

Storage​

Regions​

Config File Locations​

Project config example​

Feature config sections​

Perks​

Mailbox​

Web app settings​

Environment Variables​

Validate​

Server Config​

Logging​

CLI Commands Reference​

Top-level​

Setup & credentials​

MCP​

Other​

Chat commands (interactive)​

Interactive Setup

Profiles

Create

Switch

Use in commands

Storage

Regions

Config File Locations

Project config example

Feature config sections

Perks

Mailbox

Web app settings

Environment Variables

Validate

Server Config

Logging

CLI Commands Reference

Top-level

Setup & credentials

MCP

Other

Chat commands (interactive)