Settings & Configuration

Customize Fleet settings and preferences.

Opening Settings

Press Cmd+, to open Fleet Settings, or click the gear icon in the sidebar.

Settings are organized into sections:

Providers — AI service configuration
Models — Model management
Security — Permissions and execution tiers
MCP — Model Context Protocol servers
Skills — Installed skills
Triggers — Automation triggers
Remote — Fleet Gateway connection

Providers

Configure which AI services Fleet uses. See AI Providers for detailed setup instructions.

Cloud Providers

Connect via API key:

Anthropic API — Direct Claude API access
OpenAI — GPT models via API
Google Gemini — Gemini models via API
OpenRouter — Access to 100+ models through one API

Local Providers

Run models locally with complete privacy:

Ollama — Easy local model management
LM Studio — Desktop app for local models
Custom OpenAI-Compatible — Any compatible endpoint

Provider Configuration

For each provider, you can:

Enter API keys (stored securely in your system keychain)
Test the connection
Enable/disable the provider
View available models

Models

Manage and organize the AI models available to your agents.

Model List

Reorder models — Drag to reorder. The top model becomes the default for new agents.
Enable/disable — Toggle models on or off
Add custom models — Enter custom model IDs for providers that support them

Model Settings

For each model, you can configure:

Display name — How the model appears in Fleet
Reasoning level — For reasoning models (O1, etc.): None, Low, Medium, High
Default selection — Whether this model is selected by default

Provider-Specific Notes

Claude models — Available through Anthropic API or OpenRouter
OpenAI models — Available through OpenAI API or OpenRouter
Reasoning models — O1 and similar models support configurable reasoning levels

Security

Control what agents can do on your system. See Security & Permissions for detailed information.

Execution Mode

Choose a default permission level for all agents:

Mode	Description
Restricted	Minimal safe commands only
Read-Only	Inspection and research operations
Mutable	Create and modify files (default)
Open	Full access, no restrictions

Permission Rules

Create custom rules to fine-tune permissions:

Click Add Rule
Select the tool (e.g., system_shell, write_file)
Choose Allow or Deny
Add an optional pattern (e.g., npm *, /path/to/project/*)
Save

Rules are evaluated in order — first matching rule wins.

Secure Vault

The Secure Vault stores API keys, passwords, and other sensitive credentials securely on your machine.

How It Works:

Secrets are encrypted using macOS Keychain
Agents can reference secrets using {{vault:SECRET_NAME}} syntax in tool calls
Secrets are never sent to your LLM provider (Claude, OpenAI, etc.)
Secrets never appear in conversation history or logs

Create a Secret:

Open Settings → Security → Secure Vault
Click Add Secret
Enter a unique name (e.g., github_token, openai_api_key)
Enter the secret value
Click Save

Use a Secret: Tell your agent to use a secret by name: "Deploy using the AWS credentials from the vault"

The agent will reference it as {{vault:aws_credentials}} when making tool calls. The actual value is only used during tool execution and never exposed to the LLM.

Manage Secrets:

View all stored secret names (but not values) in Settings → Security → Secure Vault
Delete secrets by clicking the delete button next to each secret

See Secure Vault for more details.

MCP Servers

Configure Model Context Protocol servers for external tool integration.

MCP Dashboard

View and manage MCP server connections:

Server status — Connected, disconnected, or error state
Available tools — Tools provided by each server
Connection controls — Connect, disconnect, refresh

Global Configuration

MCP servers are configured in ~/Library/Application Support/com.usefamiliar.desktop/config.yaml:

mcp:
  enabled: true
  default_timeout: 30s
  servers:
    - name: github
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "{{vault:GITHUB_TOKEN}}"
      auto_connect: true

Server Settings

Setting	Description
`name`	Unique server identifier
`transport`	`stdio`, `sse`, or `websocket`
`command`	Command to spawn (stdio)
`args`	Command arguments
`url`	Server URL (sse/websocket)
`env`	Environment variables
`auto_connect`	Connect on Fleet startup
`timeout`	Request timeout

Per-Agent MCP Access

Control which servers each agent can access in their AGENT.md:

mcp_servers:
  - github
  - filesystem

mcp_permissions:
  github:
    allowed_tools: ["*"]
    denied_tools: ["delete_repo"]

mcp_approval_required:
  - github_merge_pr

See MCP Servers for full documentation.

Keyboard Shortcuts

Customize keyboard shortcuts for common actions.

Default Shortcuts

Shortcut	Action
Cmd+N	New agent
Cmd+,	Open settings
Cmd+Shift+F	Global search
Cmd+K	Command palette
Cmd+L	Focus chat input
Cmd+B	Toggle sidebar
Cmd+P	Pause/resume agent
Cmd+Shift+C	Compact conversation

Customizing Shortcuts

Click on a shortcut to edit
Press your desired key combination
Fleet will warn if there's a conflict
Click Save

Note: Some system shortcuts cannot be overridden.

Custom Prompts

Set system prompts that control how agents behave. These prompts are injected into the agent's context.

Prompt Categories

Category	Purpose
System	Core agent behavior and personality
Plan Mode	How agents approach planning tasks
Scope Proposal	How agents propose task scope
Sub-Agent	Instructions for spawned sub-agents
Tool Translation	How tool results are formatted
Conversation Summary	How conversations are summarized
Tool Result Summary	How tool outputs are condensed

Editing Prompts

Select a prompt category
Edit the prompt text
Click Save

Click Reset to Default to restore the original prompt.

Global vs. Per-Agent

Global prompts — Apply to all agents by default
Per-agent prompts — Override global prompts for specific agents (configured in agent settings)

Skills

Manage installed skills. See Skills for detailed information.

Skills Browser

View all installed skills
Search by name or description
Edit skill content
Delete skills (single or bulk)

Skill Actions

Open Folder — Open the skills directory in Finder
New Skill — Create a new skill
Refresh — Reload skills from disk

Skill Location

Skills are stored in: ~/Library/Application Support/com.usefamiliar.desktop/skills/

Triggers

Manage automation triggers. See Triggers for detailed information.

Triggers Browser

View all configured triggers
See trigger status (enabled, disabled, running)
View recent run history
Edit trigger configuration

Trigger Actions

New Trigger — Create a new trigger
Run Now — Manually execute a trigger
Enable/Disable — Toggle trigger on or off
View Logs — See execution history

Trigger Location

Triggers are stored in: ~/Library/Application Support/com.usefamiliar.desktop/triggers/

Per-Agent Settings

Each agent can have its own configuration that overrides global settings.

Accessing Agent Settings

Open the agent workspace
Click the Settings icon (gear) in the sidebar, or
Press Cmd+, while in the agent view

Model Selection

Choose which provider and model this agent uses:

Default Model — Used for main agent conversations and task execution (Sonnet recommended)
Subagent Model — Used for spawned subagents like explore and bash (Haiku recommended for efficiency)

Each can use a different provider and model. Leave empty to use global defaults.

Custom Prompts

Override global prompts for this specific agent:

Open the Prompts section in agent settings
Edit the prompt categories you want to customize
Save

Sub-Agents

Control whether this agent can spawn sub-agents:

Enable Sub-Agents — Allow the agent to delegate work
Disable Sub-Agents — Prevent sub-agent creation

Triggers & Subscriptions

Manage which triggers this agent is subscribed to:

View active subscriptions
Add new trigger subscriptions
Remove existing subscriptions

Notification Overrides

Override global notification settings for this agent:

Play Sound — Enable/disable sound notifications
Show Notification — Enable/disable system notifications

Usage Tracking

Monitor API usage and costs.

Usage Dashboard

Click the Usage icon to see:

Total API calls — Number of requests made
Total tokens — Input and output tokens consumed
Estimated costs — Based on provider pricing

Breakdown Views

By Provider — Usage grouped by AI service
By Model — Usage grouped by specific model
By Agent — Usage grouped by agent

Time Periods

View usage for: Today, This Week, This Month, All Time

Cost Management Tips

Use Haiku for most tasks (fast and cheap)
Reserve Opus for complex planning
Monitor usage weekly
Set conversation loop limits
Use local models for privacy-sensitive work

Updates

Fleet automatically checks for updates and notifies you when a new version is available. When an update is detected:

A notification appears in the app
Click to download and install the update
Restart Fleet to complete the update

Updates are served securely and include bug fixes, new features, and performance improvements.

Data & Privacy

What Stays Local

All conversations and agent configurations
Your prompts and AI responses
Files in your workspace
Secure vault contents (system keychain)
Trigger configurations and run history

What Goes to Cloud

API calls to your chosen provider(s) — only when agents execute
Anonymous usage telemetry — usage events, model selections, and token counts (never prompts or content)

Database Location

Fleet stores data in: ~/Library/Application Support/com.usefamiliar.desktop/

Tips

Start with OpenRouter — Access to 100+ models with a single API key
Set good system prompts — Consistent behavior across agents
Customize shortcuts — Optimize for your workflow
Check usage weekly — Understand your costs
Use Read-Only mode — For agents that only need to inspect, not modify
Limit sub-agents — Prevent unexpected delegation costs
Review permissions regularly — Only grant what agents need