Setup

Install Fawx, connect your AI provider, and configure how the agent works on your machine.

Install

Download the DMG from the download page. Open it, drag Fawx to your Applications folder, and launch.

Fawx is a single binary. No dependencies, no runtimes, no containers.

Terminal UI

Fawx includes a terminal interface alongside the native app. After installing, run:

fawx tui

Both interfaces share the same engine, sessions, and memory.

Setup wizard

On first launch, the setup wizard walks you through two things:

AI provider. Connect Claude, ChatGPT, or enter your own API key. Claude uses a setup token; ChatGPT uses OAuth. Both are handled automatically.
Permissions. Choose a permission preset that defines what the agent can do. Presets range from restricted (read-only file access, no shell) to open (full tool access). You can customize individual capabilities later.

You can re-run the wizard at any time:

fawx setup

AI providers

Claude (setup token)

The setup wizard generates a setup token that authenticates your Claude subscription. No API key required. Fawx stores an encrypted session credential locally.

ChatGPT (OAuth)

ChatGPT authentication uses OAuth PKCE. The wizard opens your browser, you sign in, and the token is stored locally. Refresh tokens are handled automatically.

API key (BYO)

Enter any OpenAI-compatible API key directly. This works with OpenAI, Anthropic, OpenRouter, or any provider that implements the chat completions API.

Credential security: All credentials are encrypted at rest using AES-256-GCM. They are stored in ~/.fawx/credentials.enc and never leave your machine.

Permission presets

Fawx uses capability-based permissions. Instead of asking for approval on every action, the agent operates freely within its defined boundaries. Actions outside those boundaries are denied immediately with a structured explanation.

Three built-in presets:

Open: Full tool access. File read/write, shell commands, web, git. Best for development and power users who trust the agent to work autonomously.
Standard: Read access to files, web search, and git. Write access requires the file to be in a project directory. No unrestricted shell.
Restricted: Read-only file access and web search. No shell, no file writes, no git operations.

You can also create a custom preset by toggling individual capabilities in the config file:

[permissions]
mode = "capability"
preset = "custom"

[permissions.capabilities]
file_read = true
file_write = true
shell = false
web = true
git = true

Configuration

Fawx stores its configuration at ~/.fawx/config.toml. You can edit this file directly or use the setup wizard.

Key settings

model The default model to use (e.g. "claude-sonnet-4-20250514")
thinking Thinking effort level: "off", "low", "medium", "high"
permissions.mode Either "capability" (default) or "prompt" for per-action approval
permissions.preset One of "open", "standard", "restricted", or "custom"
synthesis Custom instructions that shape the agent's behavior and tone

Updating

Fawx checks for updates on launch (when Sparkle is configured). You can also download the latest DMG from the download page at any time.

Tools →