# Foxl — Complete Documentation > All documentation pages in a single file. --- ## How Credits Work Credits are the currency for using AI models through Foxl. Every API call consumes credits based on the model and token usage. **Every new account receives 200 free welcome credits** that never expire. After the first month, free tier accounts receive 10 additional credits at the beginning of each month. ## Plans | | Free | Pro | Ultra | Enterprise | |---|------|-----|-------|------------| | **Price** | $0 forever | $20/mo | $200/mo | Contact us | | **Credits** | 10/mo | 500/mo | 10,000/mo | 50,000/mo | | **Requests** | 200/day | Unlimited | Unlimited | Unlimited | | **Models** | All Claude models | All models | All models | All models | | **Features** | Full agent, BYOK, skill library | Secure relay, cross-device sync, auto-routing | Everything in Pro, extended context, parallel agent priority | SSO, audit logs, dedicated support | | **Support** | Community | Priority | Dedicated channel | Dedicated | ## Credit Usage Credits map directly to the underlying API cost. **1 credit = $1 of model usage**. ### Per-Token Credit Cost | Model | Input (per 1M tokens) | Output (per 1M tokens) | Cache Read (per 1M) | |-------|----------------------|------------------------|---------------------| | **Opus 4.7** | 15.0 credits | 75.0 credits | 1.5 credits | | **Opus 4.6** | 15.0 credits | 75.0 credits | 1.5 credits | | **Sonnet 4.6** | 3.0 credits | 15.0 credits | 0.3 credits | | **Haiku 4.5** | 1.0 credits | 5.0 credits | 0.08 credits | | **GLM 5** | 1.0 credits | 3.2 credits | - | ### Typical Cost Per Conversation Turn | Model | Short turn (~500 tokens) | Long turn (~2K tokens) | With thinking | |-------|-------------------------|------------------------|---------------| | **Haiku 4.5** | ~0.005 credits | ~0.02 credits | ~0.05 credits | | **Sonnet 4.6** | ~0.015 credits | ~0.06 credits | ~0.15 credits | | **Opus 4.7** | ~0.05 credits | ~0.15 credits | ~0.50 credits | | **Opus 4.6** | ~0.05 credits | ~0.15 credits | ~0.50 credits | | **GLM 5** | ~0.005 credits | ~0.02 credits | ~0.06 credits | Thinking (extended reasoning) consumes output tokens. When thinking is enabled, Opus and Sonnet may use significantly more output tokens for complex tasks, which increases credit cost. Cache hits are much cheaper than fresh input - Foxl uses automatic prompt caching to reduce costs. ### What Costs Extra - **Thinking mode**: Output tokens increase 2-10x depending on task complexity - **Long conversations**: Previous messages are re-sent as input tokens each turn - **Sub-agents**: Each sub-agent is a separate API call with its own token usage - **Tool use**: Each tool call adds a model turn (tool input + result parsing) ### What's Free (Zero Credits) - **BYOK**: Using your own API keys (Anthropic, OpenAI, Google) - zero credits - **Claude Code SSO**: Using your Claude Pro/Max subscription - zero credits - **Ollama**: Local models - zero credits, zero API calls - **Memory operations**: Saving/reading workspace files is local I/O, not an API call - **Tool execution**: Running tools (exec, git, browser) is local - only the model turns that invoke them cost credits ## Credit Refresh - **Free tier**: Credits refresh on the **1st of every month at midnight UTC**. - **Paid tiers (Pro, Ultra)**: Credits refresh on your **billing renewal date**. When your subscription renews, old credits are replaced with a fresh grant for the new billing period. ## Top Up (Pro+ only) Pro and Ultra users can purchase additional credits as one-time top-ups if they run out before the monthly reset. ## Rate Limits Each plan has a daily request limit to prevent abuse: - **Free**: 200 requests/day - **Pro**: Unlimited - **Ultra**: Unlimited - **Enterprise**: Unlimited ## Check Your Balance - **Desktop**: Go to **Account** in the sidebar - **Web**: Visit [app.foxl.ai/account](https://app.foxl.ai/account) ## Upgrade To upgrade, go to your Account page and click **Upgrade to Pro**. You'll be redirected to a secure checkout page powered by Lemon Squeezy, our payment partner. ## Bring Your Own Key (Desktop Only) If you use your own API keys in the desktop app (Settings -> Providers), no Foxl credits are consumed. This works with Anthropic, OpenAI, Google, and Ollama (local, free). ## Troubleshooting ### Credits show as exhausted but I just signed up Credits may take a moment to appear. Refresh the page. If the issue persists, sign out and sign back in. ### "Rate limit exceeded" error You've hit the daily request limit for your plan. Wait until midnight UTC or upgrade to a higher plan. ### How are credits calculated? Credit cost is based on the model used and the number of input/output tokens. Opus costs more per turn than Haiku. Longer conversations use more tokens per turn. Cache hits are cheaper than cache misses. ### Do unused credits roll over? No. For free tier, credits reset on the 1st of each month. For paid tiers, credits are replaced with a fresh grant on each billing renewal date. ### Can I use Foxl for free? Yes. The free tier provides 10 credits/month. Additionally, you can use the desktop app with your own API keys (BYOK) at no credit cost, or use local models via Ollama for completely free, unlimited usage. **Need help?** - Join our [Discord community](https://discord.gg/6J53VyV2Fy) for quick answers - Email [support@foxl.ai](mailto:support@foxl.ai) for billing questions --- Foxl's most powerful feature is browser automation using your actual Chrome browser - with all your logged-in sessions intact. This is what sets Foxl apart from every other AI assistant. ## Why This Matters ChatGPT, Perplexity, and other AI tools cannot access your logged-in accounts. They can only browse the public web. Foxl is different - it controls your real Chrome browser, which means it can: - Read your Gmail or Outlook inbox - Check your Amazon order status - Navigate your company's internal tools - Fill out forms on sites where you're logged in - Extract data from authenticated dashboards ## Two Browser Tools ### browser (Playwright) Headless browser automation for general web tasks: | Action | Description | |--------|-------------| | **goto** | Navigate to a URL | | **screenshot** | Capture the current page | | **click** | Click an element | | **type** | Type text into an input | | **getText** | Extract text content | | **getHtml** | Get page HTML | | **evaluate** | Run JavaScript on the page | Best for: web scraping, form filling, data extraction from public sites. ### browser_extension (Chrome Extension) Enhanced control of your actual Chrome browser: | Action | Description | |--------|-------------| | **Tab management** | Open, close, switch, and group tabs | | **Accessibility tree** | Understand page structure and interactive elements | | **Click and type** | Interact with your real Chrome tabs | | **Scroll** | Navigate long pages | | **Screenshot** | Capture visible content | Best for: tasks requiring your login sessions - email, dashboards, authenticated sites. The Chrome Extension uses your real browser sessions. When you're logged into Gmail in Chrome, Foxl can read your email. When you're logged into Slack, Foxl can check your messages. No separate login needed. ## Installing the Chrome Extension The extension is bundled with the desktop app but requires manual installation: 1. Open Chrome and navigate to `chrome://extensions` 2. Enable **Developer mode** (toggle in top right) 3. Click **Load unpacked** 4. Select the extension directory from your Foxl installation The Chrome Extension is not yet published on the Chrome Web Store. Manual installation is required for now. ## Security Browser automation is powerful, so Foxl includes several safety measures: - **Financial site blocking**: Banking and financial sites are blocked by default via domain blacklist. You can configure allowed/blocked domains. - **Visual feedback**: The Chrome Extension shows visual indicators when the agent clicks or types. - **Action transparency**: All browser actions are logged and visible in real-time in the dashboard. ## Platform Support Browser automation detects Chrome automatically on: - **macOS**: `/Applications/Google Chrome.app` - **Windows**: Standard Chrome installation paths - **Linux**: `/usr/bin/google-chrome` or Chromium --- Foxl connects to external services in two ways: **OAuth Integrations** (one-click connect) and **Channel Skills** (messaging adapters). ## OAuth Integrations Connect services with one click from Settings - Integrations. No API keys needed - Foxl uses OAuth to act as you. | Service | Tool | Capabilities | |---------|------|-------------| | **Microsoft 365** | `outlook` | Email (inbox, read, send, reply, forward, search, folders, drafts, attachments, contacts, move, categories, update), Calendar (view, meeting, availability, room booking, search, shared list), To-Do (lists, tasks, checklist) | | **Slack** | `slack` | Search messages, read channels/DMs/threads, send messages, open conversations, reactions, file uploads, user lookup | After connecting, the corresponding tool is automatically registered and available to the agent. Disconnecting removes the tool. ### Slack Workspace Selection By default, Slack OAuth connects to the workspace you're logged into in your browser. To connect a specific workspace, enter the workspace name (the part before `.slack.com`) in the input field before clicking Connect. ## Available Channels ### Messaging | Channel | Skill | Requirements | |---------|-------|-------------| | **Discord** | `discord` | Discord bot token | | **Slack** | `slack` | Slack webhook URL or bot token | | **iMessage** | `imsg` | macOS only (uses AppleScript) | | **WhatsApp** | `wacli` | WhatsApp CLI tool (wacli binary) | ### Social Media | Channel | Skill | Requirements | |---------|-------|-------------| | **Twitter/X** | `bird` | Twitter API credentials | ### Email | Channel | Skill | Requirements | |---------|-------|-------------| | **Email (CLI)** | `himalaya` | himalaya CLI tool | | **Gmail** | `browser_extension` | Logged into Gmail in Chrome | | **Outlook** | `browser_extension` | Logged into Outlook in Chrome | ### Smart Home | Channel | Skill | Requirements | |---------|-------|-------------| | **Spotify** | `spotify` / `spotify-player` | Spotify account | | **Sonos** | `sonos` | Sonos speakers on network | | **Philips Hue** | `openhue` | Hue bridge on network | ## Setting Up a Channel ### Method 1: Skills (Recommended) Most channels are set up through skills: 1. Open the **Skills** page in the sidebar 2. Find the channel skill (e.g., `discord`, `slack`) 3. Follow the skill's setup instructions Each skill's `SKILL.md` contains detailed setup steps, including what API keys or tools are needed. ### Method 2: Browser Extension For web-based services (Gmail, Outlook, Google Calendar, Slack web), the Chrome Extension provides direct access: 1. Install the Chrome Extension 2. Log into the service in Chrome 3. Ask the agent to interact with it No API keys needed - the agent uses your existing browser sessions. ### Method 3: Shell Tools Some integrations work through CLI tools: ```bash # Signal messaging brew install signal-cli # Then: "Send a Signal message to +1234567890" # Email via himalaya brew install himalaya # Then: "Check my email" ``` ## Example Workflows ### Morning Slack Summary > "Every morning at 8am, check my Slack channels and summarize unread messages" Uses: `slack` skill + scheduling ### Discord Bot Responses > "Monitor my Discord server and respond to support questions in #help" Uses: `discord` skill + scheduling (heartbeat) ### Email-to-Slack Bridge > "When I get an email from client@company.com, send a summary to my Slack #clients channel" Uses: `browser_extension` (Gmail) + `slack` skill + scheduling ### Smart Home Automation > "At sunset, turn on the living room lights to warm white at 60%" Uses: `openhue` skill + scheduling Channel integrations require the desktop app. The web app (app.foxl.ai) is chat-only and cannot connect to external services directly. ## Adding New Channels If you need a channel that isn't available as a built-in skill, you can: 1. Create a custom skill with instructions for the agent 2. Use the `exec` tool to run CLI commands for the service 3. Use the `browser_extension` to interact with the service's web interface --- ## Discord The Foxl Discord is the best place to get help, share what you're building, and connect with other users. **[Join Foxl Discord](https://discord.gg/6J53VyV2Fy)** ### Channels | Channel | Purpose | |---------|---------| | `#general` | Chat with other Foxl users | | `#questions` | Ask questions - use `/ask` for instant AI-powered answers from the docs | | `#showcase` | Share what you built with Foxl | | `#bug-reports` | Report bugs with steps to reproduce | | `#feature-requests` | Suggest and vote on new features | | `#changelog` | Release notes and updates (read-only) | | `#private-support` | Create a private ticket for 1:1 help from the Foxl team | ### AI Bot The Foxl Bot in Discord can answer questions about Foxl using the `/ask` command: ``` /ask How do credits work? /ask How do I set up the Chrome extension? ``` The bot searches the Foxl documentation and responds with relevant answers. ### Private Support For sensitive issues or account-specific questions, click the **Create Private Ticket** button in `#private-support`. This creates a private thread visible only to you and the Foxl team. ## Email For billing, account, or legal inquiries: - **Support**: [support@foxl.ai](mailto:support@foxl.ai) ## GitHub - **Desktop app issues**: [foxl-ai/foxl/issues](https://github.com/foxl-ai/foxl/issues) ## Roadmap - Native iOS app - Q2 2026 - Native Android app - Q2 2026 - Linux desktop - planned --- Conversations are the primary way you interact with Foxl. Each conversation is a separate chat session with its own context and history. ## Creating Conversations Click **New Chat** in the sidebar or use the keyboard shortcut to start a fresh conversation. Each conversation gets: - A unique session ID - Its own message history - Separate agent context (tools used, files read, etc.) ## Conversation History All conversations are saved automatically. Access previous conversations from the sidebar, which shows: - Conversation title (auto-generated from the first message) - Last activity timestamp - Preview of the most recent message ### Desktop App Conversations are stored in the local SQLite database at `~/.foxl/pilot.sqlite`. ### Web App In the web app (app.foxl.ai), conversations are stored in your browser's localStorage. They persist across browser sessions but are local to that browser. ## Message Features ### Streaming Responses Foxl streams responses token-by-token in real-time. You can see the response forming as the AI thinks. ### Extended Thinking When using Claude Opus 4.7, Opus 4.6, or Sonnet 4.6, you can see the model's reasoning process in a collapsible "Thinking" section above the response. ### Tool Use Display When the agent uses tools (browser, code execution, file read, etc.), each tool call is shown inline with: - Tool name and action - Input parameters - Execution result - Duration ### Message Editing Click on any of your messages to edit it. Foxl will regenerate the response from that point, creating a new branch in the conversation. ### Regenerate Click the regenerate button on any assistant message to get a different response to the same input. ## Export Export conversations in multiple formats: - **JSON**: Full conversation data including tool calls and metadata - **Markdown**: Clean text format suitable for sharing or archiving Access export from the conversation menu (three-dot icon). ## Conversation with Desktop Relay When connected via Desktop Relay, conversations in the web app are routed through your desktop agent: - Messages are end-to-end encrypted - The desktop agent processes tool calls locally - Results are encrypted and sent back to the web app - Conversation history is stored on the desktop (not in the browser) When disconnected, the web app falls back to direct relay chat (no tools, history in localStorage). --- ## General ### What is Foxl? Foxl is a 24/7 personal AI agent that runs on your desktop. It can browse the web using your real Chrome sessions, run code, manage files, control smart devices, send messages, and automate recurring tasks. It comes with persistent memory and 69 installable skills. ### How is Foxl different from ChatGPT? ChatGPT is a cloud-based chatbot that generates text. Foxl is a local AI agent that takes actions - it controls your real browser with your login sessions, executes shell commands, manages git repositories, schedules tasks, and remembers everything across conversations. ChatGPT talks. Foxl does. ### What operating systems are supported? macOS 12 (Monterey) or later (Apple Silicon and Intel) and Windows 10+ (64-bit). Linux support is planned. The web app at [app.foxl.ai](https://app.foxl.ai) works on any platform, including iOS and Android. Native mobile apps are planned for Q2 2026. ## Pricing and Credits ### Is Foxl free? Yes. New accounts get 200 welcome credits (never expire), plus 10 credits per month on the free tier with 200 requests per day. You can also use the desktop app with your own API keys (BYOK) or local models (Ollama) at no cost. ### How much does Pro cost? Pro is $20/month with 500 credits and unlimited requests. Ultra is $200/month with 10,000 credits and unlimited requests. See [Credits and Billing](/docs/account/credits) for full details. ### What happens when my credits run out? You can still use the desktop app with your own API keys or local Ollama models for free. Cloud relay conversations require credits - wait for monthly refill on the 1st, or upgrade your plan. ### Can I use my own API keys? Yes. In the desktop app, go to Settings and add your API key for Anthropic, OpenAI, Google, or configure Ollama for local models. No Foxl credits are consumed when using your own keys. ## Features ### What models does Foxl support? Through the Foxl relay: Claude Opus 4.7, Opus 4.6, Sonnet 4.6, Haiku 4.5, plus GLM 5 (all via AWS Bedrock). With BYOK: any model from Anthropic, OpenAI, Google, or Ollama. ### Can Foxl access my email? Yes. Through the Chrome Extension, Foxl uses your real logged-in browser sessions. If you're logged into Gmail or Outlook in Chrome, Foxl can read and interact with your email. ### What are skills? Skills are installable capability packages (SKILL.md files) that teach the agent new abilities - Discord messaging, Spotify control, GitHub management, weather lookup, and 60+ more. Browse them in the Skills page. See [Skills](/docs/skills). ### Can I create custom skills? Yes. Create a `SKILL.md` file in `~/.foxl/skills/your-skill/` with YAML frontmatter and markdown instructions. The agent discovers it automatically. ## Security and Privacy ### Does Foxl store my data on its servers? No. All data (conversations, memory, files) is stored locally on your machine. The cloud relay handles only authentication and model routing. See [Security and Privacy](/docs/security). ### Is it safe to give Foxl browser access? Yes. Financial sites are blocked by default. All browser actions are visible in real-time. Sensitive operations require your explicit approval. You can configure domain whitelists and blacklists. ### Where is my data stored? On your machine at `~/.foxl/` (macOS/Linux) or `%USERPROFILE%\.foxl\` (Windows). You can change this with the `FOXL_HOME` environment variable. All memory is stored as readable markdown files - no hidden or encrypted data stores. ## Desktop and Web App ### Can I use Foxl without the desktop app? Yes. The web app at [app.foxl.ai](https://app.foxl.ai) provides AI chat. However, the full agent experience (browser, code, files, git, memory, scheduling) requires the desktop app. ### How do I connect the desktop app to the web app? Generate a 6-character pairing code in the desktop app Settings, then enter it in the web app Settings. The connection is end-to-end encrypted. See [Desktop Relay](/docs/getting-started/desktop-relay). ### What happens when the desktop app is offline? The web app falls back to chat-only mode - direct AI conversation through the cloud relay without agent tools. ## Troubleshooting ### The app won't open on macOS Right-click the app and select "Open" to bypass Gatekeeper on first launch. Foxl is notarized by Apple. ### Credits are not showing up Sign out and sign back in. Credits may take a moment to sync after account creation. ### Chrome Extension is not connecting Make sure the desktop app is running. Check that the extension is enabled in `chrome://extensions`. The extension communicates with the desktop agent via WebSocket on localhost. ### Need more help? - Join our [Discord community](https://discord.gg/6J53VyV2Fy) - use `/ask` for instant AI-powered answers - Create a private support ticket in the Discord `#private-support` channel - Email [support@foxl.ai](mailto:support@foxl.ai) for billing or account questions --- The Chrome Extension is what gives Foxl access to your real Chrome browser with all your logged-in sessions. It connects your browser to the desktop agent via WebSocket. ## Installation The extension is not yet on the Chrome Web Store. Manual installation is required. ### Step 1: Locate the Extension The extension files are bundled with the Foxl desktop app. After installing Foxl, find the extension in the application bundle. ### Step 2: Load in Chrome 1. Open Chrome and go to `chrome://extensions` 2. Enable **Developer mode** (toggle in the top-right corner) 3. Click **Load unpacked** 4. Select the `chrome-extension` folder from your Foxl installation ### Step 3: Verify Connection Once loaded, you should see the Foxl icon in your Chrome toolbar. The icon shows: - **Green**: Connected to the desktop agent - **Gray**: Not connected (desktop app may not be running) ## What the Extension Does ### Tab Management The agent can open, close, switch between, and group your Chrome tabs. This lets it navigate between multiple sites during complex tasks. ### Accessibility Tree The extension extracts the accessibility tree from any page - a structured representation of all interactive elements (buttons, links, inputs, headings). This is how the agent "sees" and understands web pages. ### Interaction The agent can click buttons, type into input fields, scroll pages, and submit forms - all in your real Chrome browser with your actual sessions. ### Visual Indicators When the agent interacts with a page, visual highlights show exactly what it's clicking or typing. You can watch the agent work in real-time. ### Screenshots The extension can capture screenshots of any tab, which the agent uses for visual understanding and verification. ## Side Panel Click the Foxl icon in the Chrome toolbar to open the side panel. The side panel provides: - Connection status to the desktop agent - Recent agent activity - Quick access to settings ## Security The extension communicates with the desktop agent over a local WebSocket connection (localhost only). It does not send any data to external servers. - All communication is local (localhost WebSocket) - The extension only activates when the desktop agent requests it - Financial sites are blocked by default - You can review all extension permissions in Chrome's extension settings ## Troubleshooting ### Extension shows "Disconnected" Make sure the Foxl desktop app is running. The extension connects to the local agent server. ### Extension not appearing in Chrome Verify that Developer mode is enabled and the extension loaded without errors in `chrome://extensions`. ### Pages not responding to agent commands Some pages block automation (CAPTCHA, certain SPAs). Try refreshing the page. The agent may fall back to the Playwright-based `browser` tool for these cases. --- The Desktop Relay lets you connect your desktop Foxl agent to the web app at [app.foxl.ai](https://app.foxl.ai). When connected, the web app routes your conversations through your desktop agent, giving you full tool access from any browser. ## How It Works | Mode | What you get | |------|-------------| | **Connected** | Full agent: browser automation, code execution, file management, git, memory, skills, terminal | | **Disconnected** | Chat-only: direct AI conversation through the cloud relay (no tools) | ## Connecting Your Devices ### Step 1: Sign In on Desktop Open the desktop app and sign in with your Foxl account (Google, Apple, or magic link). Navigate to **Settings** > **Relay** and toggle **Remote Access** on. ### Step 2: Sign In on the Web App Open [app.foxl.ai](https://app.foxl.ai) and sign in with the same account. Your desktop is automatically detected - no pairing code needed. ### Step 3: Connected The web app connects to your desktop agent automatically. When your desktop app is running, the web app has full tool access. Connection is automatic - just sign in with the same account on both devices. Multiple web browsers can connect to a single desktop. ## Connection Status The web app shows your connection status: - **Desktop Online**: Connected to your desktop agent. Full tool access available. - **Desktop Offline**: Desktop app is not running or unreachable. Chat-only mode active. When the desktop comes back online, the web app detects it automatically and reloads to restore full agent mode. ## Remote Terminal When connected, you can access your desktop terminal from the web app: - Spawn terminal sessions directly from the chat UI - View real-time terminal output remotely - Multiple tabs and split view supported - The agent can also use the terminal tool to run commands ## End-to-End Encryption All communication between your web browser and desktop app is end-to-end encrypted: - **Key exchange**: ECDH P-256 (Elliptic Curve Diffie-Hellman) - **Encryption**: AES-256-GCM - **Forward secrecy**: Ephemeral keys generated per connection - **Verification**: E2E fingerprint displayed in the web app for manual verification The relay server routes encrypted messages but cannot read their contents. Your conversations, file contents, and tool results are encrypted end-to-end. ## Device Management From the desktop app Settings > Relay, you can: - **View connected devices**: See all web browsers connected to your desktop - **Disconnect a device**: Revoke access for a specific browser - **Toggle remote access**: Enable or disable web client connections ## Offline Fallback When your desktop is disconnected, the web app automatically switches to **relay direct mode**: - Chat continues working through the cloud relay (no tools, but AI conversation works) - Relay conversations are stored locally in the browser - When desktop reconnects, the app automatically switches back to full agent mode ## Sleep/Wake Reconnection Foxl automatically reconnects after your laptop sleeps: - The desktop app detects sleep/wake events via Durable Object ping timing - If no ping is received within 90 seconds, a reconnect is triggered - The web app detects the reconnection and reloads to restore full agent access ## Troubleshooting ### Web app says "Desktop Offline" but the app is running - Check that both devices are connected to the internet - Wait a few seconds - the web app detects desktop status automatically - Try a hard refresh (Cmd+Shift+R) in the web app - Toggle the relay off/on in the desktop app Settings ### Connection drops after laptop sleep - Foxl should auto-reconnect within a few seconds of waking - If it doesn't reconnect, toggle the relay off/on in the desktop app Settings ### Connection drops frequently - Ensure your network allows WebSocket connections - Check if a firewall or VPN is blocking the connection --- ## System Requirements ### macOS - macOS 12 (Monterey) or later - Apple Silicon (M1+) or Intel - Node.js 22+ (for the embedded AI agent) ### Windows - Windows 10 or later (64-bit) - Node.js 22+ (for the embedded AI agent) ## Download **macOS:** **[Download Foxl for Mac (Universal)](https://github.com/foxl-ai/foxl/releases/latest/download/Foxl-latest-universal.dmg)** The universal build works on both Apple Silicon and Intel Macs. **Windows:** **[Download Foxl for Windows (Installer)](https://github.com/foxl-ai/foxl/releases/latest/download/Foxl-latest-setup.exe)** NSIS installer with auto-update support. **[Download Foxl for Windows (Portable ZIP)](https://github.com/foxl-ai/foxl/releases/latest/download/Foxl-latest-portable.zip)** No installation needed. Extract and run. ## Installation ### macOS 1. Open the downloaded `.dmg` file 2. Drag **Foxl** to your Applications folder 3. Open Foxl from Applications 4. On first launch, macOS may ask you to confirm - click "Open" ### Windows **Installer:** Run `Foxl-latest-setup.exe` and follow the prompts. Foxl will be installed and a desktop shortcut created. **Portable:** Extract the ZIP and run `Foxl.exe`. No installation required. Windows may show a SmartScreen warning on first launch since the app is self-signed. Click "More info" then "Run anyway" to proceed. ## Sign In After launching Foxl, sign in with your Google or Apple account to get 200 free welcome credits and start chatting with AI. ## Auto-Updates Foxl automatically checks for updates and installs them when you quit the app. You'll always have the latest version. ## Need Help? If you run into issues, check [Troubleshooting](/docs/troubleshooting) or ask in our [Discord community](https://discord.gg/6J53VyV2Fy). --- ## app.foxl.ai No installation needed - open [app.foxl.ai](https://app.foxl.ai) in any browser and start chatting with AI instantly. ## Features - **Chat with AI models** - Claude Opus 4.7, Sonnet 4.6, Haiku 4.5 - **Extended thinking** - watch the AI reason through complex problems - **Conversation history** - saved locally in your browser - **Model selection** - switch between models per conversation - **Dark mode** - automatic or manual theme switching ## Sign In Click **Sign In** to create a free account. You can sign in with: - **Google** - one-click sign in - **Apple** - privacy-friendly sign in - **Email** - magic link (no password needed) ## Credits Every new account gets **200 free welcome credits** (never expire), plus **10 credits per month** on the free tier. Each credit covers approximately one conversation turn depending on the model used. | Model | Credits per turn (approx.) | |-------|---------------------------| | Haiku 4.5 | ~0.01 | | Sonnet 4.6 | ~0.05 | | Opus 4.7 | ~0.15 | ## Limitations The web app is a lightweight chat interface. For the full agent experience (browser automation, code execution, file management, git, memory), use the [desktop app](/docs/getting-started/download). --- Welcome to Foxl - your personal AI agent that runs on your desktop and in the cloud. ## What is Foxl? Foxl is an autonomous AI agent that can browse the web using your real Chrome sessions, run code, search your files, manage git repositories, send messages, and much more. It runs locally on your Mac or Windows PC with a cloud relay for authentication and multi-model AI access. **Key differentiators:** - **Real browser control** - uses your actual Chrome with all your logged-in sessions - **Persistent memory** - remembers your preferences and context across conversations - **24/7 scheduling** - automates recurring tasks without prompting - **Skill library** - messaging, productivity, media, development tools - **Local-first** - your data never leaves your machine ## Get Started ## Features ## Account and Help --- Foxl has a persistent memory system that learns about you over time. The more you use it, the better it understands your preferences, workflows, and context. ## Two Types of Memory ### Database Memory (SQLite) Key-value pairs stored in SQLite with tags for organization. Used for structured data that the agent needs to recall quickly. - **memory_save**: Store a piece of information with a key and optional tags - **memory_recall**: Search memory by key, value content, or tags ### Workspace Memory (Markdown Files) Human-readable markdown files stored in your workspace directory. These are the heart of Foxl's personalization: | File | Purpose | |------|---------| | **SOUL.md** | Agent personality, behavior rules, and system prompt | | **USER.md** | Information about you - preferences, work context, communication style | | **MEMORY.md** | General knowledge, notes, and reference material | | **AGENTS.md** | Sub-agent configurations | | **TOOLS.md** | Tool usage notes and preferences | | **HEARTBEAT.md** | Heartbeat schedule configuration | | **BOOTSTRAP.md** | Initial setup instructions | | **memory/YYYY-MM-DD.md** | Auto-generated daily conversation summaries | ### SOUL.md - Your System Prompt The most important file. **SOUL.md is injected as the system prompt** (the `system` role in the API call) on every single conversation turn. This means the model reads it before every response. Use it to define: - **Communication style**: "Be concise", "Respond in Korean when I write in Korean", "Never use emojis" - **Technical preferences**: "Use TypeScript", "Prefer pnpm over npm", "Always use functional components" - **Behavior rules**: "Always check git status before committing", "Ask before deleting files" - **Domain context**: "I work on a SaaS product", "My stack is Next.js + PostgreSQL" The agent follows these instructions in every conversation. Changes take effect immediately. ### USER.md - About You The agent writes and updates this file as it learns about you. Contains: - Your name, role, and timezone - Work context and current projects - Communication preferences (formal/casual, language) - Technical skill level and areas of expertise You can edit this directly or tell the agent: "I'm a backend engineer who prefers Go." ### MEMORY.md - Knowledge Base A general-purpose notes file where the agent stores information it wants to remember: - Project decisions and rationale - API keys and service configurations (non-sensitive) - Frequently referenced facts - Meeting notes and action items ### AGENTS.md - Sub-Agent Definitions Configure specialized sub-agents that the main agent can spawn for specific tasks. Each sub-agent can have its own system prompt, model, and tool restrictions. ### TOOLS.md - Tool Preferences Notes about how the agent should use its tools. For example: "When using the browser tool, always use Chrome", "Prefer code_search over grep for large repos." ### HEARTBEAT.md - Scheduled Tasks Configure the agent's heartbeat - periodic tasks that run on a schedule. The morning briefing, automated checks, and recurring workflows are defined here. ### BOOTSTRAP.md - First Run Setup Instructions that run when Foxl starts for the first time in a new workspace. Use it to set up project-specific context, install dependencies, or configure tools. ### memory/YYYY-MM-DD.md - Daily Journals Auto-generated at the end of each day with activity. Contains a summary of conversations, decisions made, and action items. Builds into a searchable history of your interactions. ## Customizing Your Agent with SOUL.md **SOUL.md** is the most powerful customization file - it defines your agent's personality, behavior rules, and system prompt. Think of it as the "character sheet" for your AI. ### What to Put in SOUL.md ```markdown # My Foxl Agent ## Personality - Respond concisely and directly - Use Korean when I write in Korean, English when I write in English - Never use emojis unless I ask ## Rules - Always check git status before committing - Prefer TypeScript over JavaScript - Use pnpm, not npm ## Context - I'm a full-stack developer working on a SaaS product - My stack: Next.js, PostgreSQL, Tailwind CSS - My timezone: KST (UTC+9) ``` ### How to Edit SOUL.md 1. **From the app**: Go to **Workspace** in the sidebar, click **SOUL.md**, and edit directly 2. **From the terminal**: Open `~/.foxl/workspace/SOUL.md` (production) or `./data/workspace/SOUL.md` (dev) in any text editor 3. **Through conversation**: Tell the agent "add to your rules: always use dark mode in code examples" and it will update SOUL.md Changes take effect immediately - no restart needed. SOUL.md content is included in every conversation as the system prompt. ## How Memory Works The agent automatically: 1. Saves important information from conversations (your preferences, decisions, context) 2. Recalls relevant memories when they apply to the current conversation 3. Generates daily summaries of what was discussed You don't need to tell Foxl to remember things - it does this naturally. But you can also explicitly ask it to remember or forget specific information. ## Privacy and Transparency All memory is stored as plaintext markdown files on your machine. There is no hidden data store. You can read, edit, or delete any memory file at any time. - **Location**: `~/.foxl/workspace/` (macOS/Linux) or `%USERPROFILE%\.foxl\workspace\` (Windows) - **Format**: Standard markdown - open with any text editor - **No cloud sync**: Memory never leaves your machine - **No black box**: Every piece of stored knowledge is visible and editable ## Viewing and Editing Memory You can browse and edit all memory files from the **Workspace** page in the sidebar, from the filesystem, or through conversation ("What do you know about me?"). See [Workspace](/docs/workspace) for details on browsing, editing, and file locations. ## Context Window and Token Impact Every conversation turn, the following is sent to the model as input tokens: | Component | Approximate tokens | When | |-----------|-------------------|------| | System prompt (SOUL.md + workspace context) | 500-2,000 | Every turn | | Tool definitions (~19 tools in full profile) | ~3,800 | Every turn | | Conversation history (previous messages) | Varies | Every turn (grows with conversation) | | Your current message | Varies | Current turn | This means a fresh conversation starts at roughly 5,000-6,000 input tokens before you type anything. As the conversation grows, previous messages accumulate. Foxl uses **automatic context compaction** - when the conversation approaches the context window limit, older messages are summarized to free up space. ### Tips for managing token usage - Keep SOUL.md concise - every extra line costs input tokens on every turn - Use the **Minimal** tool profile (Settings > Tools) if you don't need every tool (~1,600 tokens instead of ~3,800) - Long conversations cost more per turn because history accumulates - Prompt caching reduces repeat costs - Foxl enables this automatically ## Memory and Credits Memory save and recall are local operations - writing to SQLite or markdown files does not call the LLM and costs zero credits. However, when the agent reads memory content back into the conversation, that content becomes part of the input tokens sent to the model. More stored memory means more tokens consumed per turn. ## Daily Summaries At the end of each day with activity, Foxl generates a summary file (`memory/YYYY-MM-DD.md`) capturing key topics, decisions, and action items from your conversations. These build up into a searchable journal of your interactions. --- Foxl supports models from multiple providers. Use Foxl relay credits, your own API keys (BYOK), or your ChatGPT Plus/Pro subscription (OAuth). ## Foxl Relay Models Included with your Foxl plan. No setup needed - just sign in and chat. | Model | Provider | Context | Best For | |-------|----------|---------|----------| | **Claude Opus 4.7** | Bedrock | 1M tokens | Most capable for complex reasoning + agentic coding | | **Claude Opus 4.6** | Bedrock | 1M tokens | Previous flagship; still 1M context | | **Claude Sonnet 4.6** | Bedrock | 1M tokens | Best balance of speed and quality | | **Claude Haiku 4.5** | Bedrock | 200K tokens | Fastest model, near-frontier intelligence | | **GLM 5** | Bedrock (Z.AI) | 200K tokens | Agentic coding, long-horizon tasks | ## Subscription (OAuth) Models Use your existing subscriptions. Desktop only - see [Providers](/docs/providers) for setup. Foxl calls the vendor API directly with your OAuth token; tool use, adaptive thinking, and streaming all flow through Foxl's normal agent loop. ### Claude Code (Anthropic Pro/Max) | Model | Context | Best For | |-------|---------|----------| | **Opus 4.7** (Claude Code mode) | 1M tokens | Complex reasoning, coding, analysis | | **Sonnet 4.6** (Claude Code mode) | 1M tokens | Balanced speed and quality | Claude Code (OAuth) runs in **compatibility mode** so requests route through your Claude Pro/Max subscription instead of pay-as-you-go "Extra usage". In this mode, Foxl-specific tools (memory, subagents, schedules, channel send, browser extension, view image) are disabled - only Bash, Read, Grep, and WebFetch are available. Haiku 4.5 is not exposed in this mode. For the full Foxl tool surface, use an Anthropic API key (BYOK) or the foxl.ai relay. ### OpenAI (ChatGPT Plus/Pro) | Model | Context | Best For | |-------|---------|----------| | **GPT-5.5** | 1M tokens | Latest frontier, reasoning + streaming | | **GPT-5.4** | 1M tokens | General-purpose reasoning | | **GPT-5.4 Mini** | 400K tokens | Fast, cost-aware tasks | | **GPT-5.3 Codex** | 400K tokens | Code-heavy tasks | Also exposed as a built-in tool: `gpt-image-2` via the `generate_image` tool. No API key, no per-image billing - powered by your ChatGPT Plus/Pro OAuth session. Accepts up to 10 input images for edit / compose mode. ### Gemini CLI (Google) | Model | Context | Best For | |-------|---------|----------| | **Gemini 2.5 Pro** | 1M tokens | Long documents, deep analysis | | **Gemini 2.5 Flash** | 1M tokens | Fast, cost-effective | ## BYOK Models Bring your own API key to access models from any provider. See [AI Providers](/docs/providers) for setup. | Model | Provider | Context | API Key From | |-------|----------|---------|--------------| | **Claude Opus 4.7** | Anthropic | 1M tokens | [console.anthropic.com](https://console.anthropic.com) | | **Claude Opus 4.6** | Anthropic | 1M tokens | [console.anthropic.com](https://console.anthropic.com) | | **Claude Sonnet 4.6** | Anthropic | 1M tokens | [console.anthropic.com](https://console.anthropic.com) | | **Claude Haiku 4.5** | Anthropic | 200K tokens | [console.anthropic.com](https://console.anthropic.com) | | **GPT-4.1** | OpenAI | 1M tokens | [platform.openai.com](https://platform.openai.com) | | **GPT-4.1 Mini** | OpenAI | 1M tokens | [platform.openai.com](https://platform.openai.com) | | **o3** | OpenAI | 200K tokens | [platform.openai.com](https://platform.openai.com) | | **Gemini 2.5 Pro** | Google | 1M tokens | [aistudio.google.com](https://aistudio.google.com) | | **Gemini 2.5 Flash** | Google | 1M tokens | [aistudio.google.com](https://aistudio.google.com) | | **Llama 3, Mistral, etc.** | Ollama | Varies | Free - [ollama.com](https://ollama.com) | ## Adaptive Thinking Claude Opus 4.7, Opus 4.6, and Sonnet 4.6 support **adaptive thinking** - Claude dynamically decides when and how much to think based on the complexity of your request. No manual budget setting needed. - **Simple questions**: Claude responds directly without thinking overhead - **Complex problems**: Claude automatically engages deep reasoning - **Agentic workflows**: Claude can think between tool calls (interleaved thinking) Adaptive thinking (`type: "adaptive"`) is the recommended mode for Opus 4.7, Opus 4.6, and Sonnet 4.6. Haiku 4.5 uses `type: "enabled"` with a `budget_tokens` parameter instead. Haiku 4.5 also supports extended thinking with `type: "enabled"` and `budget_tokens`. You can toggle thinking on/off in the model selector. ### Thinking and Cost Thinking consumes **output tokens**. When thinking is enabled, the model may use 2-10x more output tokens depending on task complexity. This directly increases credit cost: - **Simple question without thinking**: ~0.01 credits (Sonnet) - **Same question with thinking**: ~0.05-0.15 credits (Sonnet) - **Complex reasoning with thinking**: ~0.30-1.0 credits (Opus) For cost-sensitive usage, disable thinking for simple tasks. For complex coding, analysis, or multi-step reasoning, thinking significantly improves quality and is worth the extra cost. See [Credits](/docs/account/credits) for detailed per-token pricing. ## Model Selection ### Desktop App Click the model name in the chat input area to switch models. Your selection persists across conversations. ### Web App Click the model selector dropdown to choose a different model. The selection is saved in your browser. ## Bring Your Own Key (Desktop Only) In the desktop app, you can use your own API keys instead of Foxl credits: 1. Go to **Settings** 2. Select a provider (Anthropic, OpenAI, Google, etc.) 3. Enter your API key 4. Select a model from that provider When using your own keys, no Foxl credits are consumed. ### Subscription OAuth You can use your ChatGPT Plus/Pro subscription directly - no API key needed. **OpenAI OAuth** 1. Run `npx @openai/codex login` to create `~/.codex/auth.json` 2. Select **OpenAI (OAuth)** in Settings > Providers - Foxl calls OpenAI's Codex Responses API directly with your subscription token Foxl auto-detects your credentials. See [AI Providers](/docs/providers) for details on all supported providers. --- The morning briefing is Foxl's signature use case - a daily automated summary of everything you need to know before starting your day. ## What It Does Every morning at your chosen time, Foxl automatically: 1. Checks your **email** (Gmail, Outlook - via Chrome Extension) 2. Reviews your **calendar** for today's meetings 3. Summarizes **important messages** from Slack or Teams 4. Checks the **weather** for your location 5. Delivers a structured briefing to your dashboard ## Setup ### Quick Setup (Recommended) Just tell the agent: > "Set up a morning briefing for me at 7am. Check my Gmail, Google Calendar, and give me the weather for Seoul." The agent will: - Create a cron schedule (`0 7 * * *`) - Configure the briefing sources - Start delivering briefings the next morning ### Manual Setup 1. Open the **Schedules** page in the sidebar 2. Create a new schedule with type **Cron** 3. Set the expression to `0 7 * * *` (7:00 AM daily) 4. Enter the task prompt describing what to check ## Prerequisites For the full briefing experience, you need: - **Desktop app running** - schedules execute locally - **Chrome Extension installed** - for email and calendar access - **Logged into Gmail/Outlook** in Chrome - the agent uses your real sessions - **Logged into Google Calendar** in Chrome - for calendar events The morning briefing uses the Chrome Extension to access your logged-in accounts. No additional OAuth or API keys are needed - if you can see your email in Chrome, Foxl can read it. ## Customization You can customize the briefing to include any combination of: - Email summary (unread count, important senders, action items) - Calendar events (today's meetings with times and attendees) - Weather forecast - News headlines (from specific sources) - Git repository activity - Service health checks - Custom data from any website you're logged into Tell the agent what you want changed: > "Add my GitHub notifications to the morning briefing" > "Skip the weather, add Hacker News top 5 instead" > "Change the briefing time to 6:30am" ## Example Briefing Output ``` Good morning! Here's your briefing for Monday, March 17, 2026: EMAIL (3 unread) - [Priority] Project deadline moved to Friday - from team-lead@company.com - Meeting notes from last week's sprint review - Newsletter from TechCrunch CALENDAR (2 events today) - 10:00 AM - Team standup (30 min, Google Meet) - 2:00 PM - Client demo with Acme Corp (1 hr, Zoom) WEATHER - Seoul: 12C, partly cloudy, high of 18C GITHUB - 2 PRs awaiting your review - CI passed on main branch ``` ## How Credits Work Credits are consumed per LLM API call based on token usage (input + output tokens multiplied by the model's pricing). A morning briefing involves multiple conversation turns as the agent reads email, checks calendar, and composes the summary. The exact credit cost depends on: - Which model you use (Haiku is cheapest, Opus is most expensive) - How much content the agent processes (longer emails = more tokens) - Number of tool calls in the briefing flow With BYOK or Ollama, no relay credits are consumed. --- Foxl supports multiple AI providers. You can use Foxl credits through the cloud relay, or bring your own API keys for direct access. ## Default: Foxl Relay By default, Foxl routes AI requests through the cloud relay at relay.foxl.ai. This uses your Foxl credits and provides access to Claude models via AWS Bedrock. No configuration needed - sign in and start chatting. ## OAuth Providers (Subscription Login) Use your existing Claude, Gemini, or ChatGPT subscriptions directly in Foxl - no API key needed. Foxl reads OAuth credentials created by each vendor's login flow. OAuth providers are desktop-only. Authentication stays local - your subscription tokens never leave your machine except to reach the vendor's API. No Foxl credits consumed. Unofficial community integration. Treat the auth file like a password - keep it on a trusted machine, don't share it, and don't pool access. Misuse may violate the provider's terms and result in rate limits or account suspension. Use at your own risk. ### Gemini CLI (Google AI) Use your Google AI subscription or API key. 1. Install: `npm install -g @google/gemini-cli` 2. Authenticate: `gemini auth login` or set `GEMINI_API_KEY` 3. Select **Gemini CLI** in Settings > Providers Models: Gemini 2.5 Pro, Gemini 2.5 Flash. Credentials from `~/.gemini/settings.json` or environment variable. ### Claude Code (Anthropic Pro/Max) Use your Claude Pro or Claude Max subscription. Foxl calls `api.anthropic.com` directly with your Claude Code OAuth token - no CLI subprocess. 1. Run the official login once inside Claude Code: `claude /login` (or `claude setup-token`) 2. Select **Claude Code (OAuth)** in Settings > Providers, then pick Opus 4.7 or Sonnet 4.6 from the model selector Models: Opus 4.7 and Sonnet 4.6 are exposed in **compatibility mode** so requests route through your Claude Pro/Max subscription instead of pay-as-you-go "Extra usage". Tokens auto-refresh in the background. Compatibility mode disables Foxl-specific tools (memory, subagents, schedules, channel send, browser extension, view image). Only Bash, Read, Grep, and WebFetch are available while Claude Code OAuth is active. If you need the full Foxl tool surface, use an Anthropic API key (BYOK) or the foxl.ai relay instead. Haiku 4.5 is intentionally not exposed in this mode - it does not reliably stay on the subscription pool once more than a few tools are in play. ### OpenAI (ChatGPT Plus/Pro) Use your ChatGPT Plus or Pro subscription - Foxl calls OpenAI's Codex Responses API directly with your OAuth token. No local CLI subprocess or proxy server needed. 1. Run the official login once: `npx @openai/codex login` (creates `~/.codex/auth.json`) 2. Select **OpenAI (OAuth)** in Settings > Providers Models: **GPT-5.5** (1M context), **GPT-5.4** (1M context), **GPT-5.4 Mini** (400K), **GPT-5.3 Codex** (400K). The live catalog is fetched from Codex per account, so your actual selection may differ slightly based on what ChatGPT rolls out to your tier. Tokens auto-refresh in the background via the OAuth refresh flow. Image generation is available through the `generate_image` tool (powered by `gpt-image-2`), which uses the same OAuth credentials. See [Agent Tools - Media](/docs/tools#media) for details. ## Bring Your Own Key (BYOK) Add your own API keys to use models directly without consuming Foxl credits. Works on both desktop and web (app.foxl.ai). ### Anthropic Direct access to Claude models via the Anthropic API. 1. Go to **Settings** > **Providers** 2. Select **Anthropic** 3. Enter your API key from [console.anthropic.com](https://console.anthropic.com) 4. Select a model (Claude Opus 4.7, Opus 4.6, Sonnet 4.6, Haiku 4.5) ### OpenAI Access GPT-4o, GPT-4, and other OpenAI models. 1. Go to **Settings** > **Providers** 2. Select **OpenAI** 3. Enter your API key from [platform.openai.com](https://platform.openai.com) 4. Select a model ### Google (Gemini) Access Gemini models via Google AI. 1. Go to **Settings** > **Providers** 2. Select **Google** 3. Enter your API key from [aistudio.google.com](https://aistudio.google.com) 4. Select a Gemini model ### Ollama (Local Models) Run AI models entirely on your machine with zero cost and full privacy. 1. Install Ollama from [ollama.com](https://ollama.com) 2. Pull a model: `ollama pull llama3` or `ollama pull mistral` 3. In Foxl Settings > Providers, select **Ollama** 4. Foxl auto-detects running Ollama models Ollama models run entirely on your machine. No internet connection, no API calls, no credits consumed. Perfect for privacy-sensitive work. ### AWS Bedrock For users with their own AWS account and Bedrock access. 1. Configure AWS credentials (`~/.aws/credentials` or environment variables) 2. In Settings > Providers, select **AWS Bedrock** 3. Ensure the models you want are enabled in your AWS Bedrock console ## Provider Health Check The Settings > Providers page shows the status of each configured provider: - **Connected**: Provider is reachable and API key is valid - **Error**: API key is invalid or provider is unreachable - **Not configured**: No API key entered ## Model Switching You can switch between models and providers at any time using the model selector in the chat input area. Your selection persists across conversations. ## Cost Comparison | Provider | Cost | Privacy | Speed | |----------|------|---------|-------| | Foxl Relay | Credits (included in plan) | Data routed through relay | Fast (AWS Bedrock) | | Gemini CLI | Free (subscription/API key) | Local CLI to Google | Fast | | OpenAI (OAuth) | Free (ChatGPT Plus/Pro) | Direct to chatgpt.com/backend-api/codex, tokens stay local | Fast | | Anthropic BYOK | Pay-per-use to Anthropic | Direct to Anthropic | Fast | | OpenAI BYOK | Pay-per-use to OpenAI | Direct to OpenAI | Fast | | Google BYOK | Pay-per-use to Google | Direct to Google | Fast | | Ollama | Free | 100% local, no network | Depends on hardware | --- Foxl can run tasks on schedules - automating work 24/7 without you having to prompt it each time. ## Three Trigger Types ### Cron (Time-Based) Standard cron expressions for time-based scheduling. Tell the agent in natural language and it creates the schedule automatically. | What you say | Cron expression | When it runs | |-------------|----------------|--------------| | "Every morning at 7am" | `0 7 * * *` | Daily at 7:00 AM | | "Every Monday at 9am" | `0 9 * * 1` | Mondays at 9:00 AM | | "Every hour" | `0 * * * *` | Top of every hour | | "First of every month" | `0 0 1 * *` | 1st of month, midnight | ### Heartbeat (Periodic) Runs at fixed intervals. Good for monitoring and status checks. - Default interval: 5 minutes - Configurable per schedule - Ideal for: checking unread messages, service monitoring, status updates ### Webhook (External Trigger) HTTP endpoints that trigger agent tasks when called from external services. - GitHub push events trigger code review - Calendar events trigger meeting preparation - Custom integrations via webhook URLs ## Creating Schedules Just tell the agent what you want automated: > "Summarize my email every morning at 8am" The agent will: 1. Create a cron schedule (`0 8 * * *`) 2. Set the task prompt ("Check Gmail and summarize unread emails") 3. Start executing on schedule You can also be more specific: > "Every weekday at 6pm, check my GitHub notifications and send me a summary on Slack" ## Managing Schedules Open the **Schedules** page in the sidebar to see: - All active schedules with their trigger type and timing - Human-readable descriptions (e.g., "Every day at 7:00 AM") - Run history with success/failure status and duration - Enable/disable toggles for each schedule ## Use Cases ### Morning Briefing Schedule a daily briefing that checks your email, calendar, and news: > "Every morning at 7am, read my Gmail, check my Google Calendar for today, and give me a briefing" ### Competitive Monitoring Track competitor activity on a daily basis: > "Every day at noon, check competitor.com for any new blog posts or product updates" ### Git Status Reports Get daily summaries of repository activity: > "Every weekday at 5pm, show me a summary of today's git commits across all my repos" ### Health Checks Monitor your services with regular pings: > "Every 5 minutes, check if api.myapp.com is responding and alert me if it's down" The desktop app must be running for schedules to execute. Foxl runs locally - if you quit the app or your machine sleeps, schedules pause. **Missed schedules are skipped, not queued.** If a cron job was supposed to run at 7am but your laptop was asleep, it will not execute retroactively when you wake up. Only the next scheduled time fires. Plan accordingly for critical automations - keep the app running or use an always-on machine. ## Execution History Every schedule run is logged with: - Timestamp - Duration - Success or failure status - Output summary View the full history on the Schedules page or ask the agent: "Show me the last 5 runs of my morning briefing schedule." --- Foxl is designed with a local-first architecture. Your data stays on your machine, your memory is transparent, and you control what the agent can do. ## Core Principles 1. **Local execution**: The agent runs on your Mac. Data does not leave your machine unless you explicitly use cloud services. 2. **Transparency**: All memory is stored as readable markdown files. No hidden databases or opaque data stores. 3. **User control**: Every sensitive action requires your approval. You decide what the agent can and cannot do. ## Tool Permissions Each tool has a permission level: | Permission | Tools | Behavior | |-----------|-------|----------| | **Auto-approved** | file_read, web_fetch, memory, code_search | Runs without asking | | **Requires confirmation** | exec (shell), git push/commit | Asks before executing (can be set to "always approve") | | **Restricted** | browser on financial sites | Blocked by default | You can adjust these permissions in **Settings** > **Tools**. ## Browser Security - **Domain whitelist/blacklist**: Configure which sites the agent can access - **Financial site blocking**: Banking and trading sites are blocked by default - **Visual indicators**: The Chrome Extension shows what the agent is doing in your browser - **Action logging**: Every browser action is recorded in the audit log ## Code Execution Sandbox The `exec` tool (shell command execution) includes safety measures: - **Working directory restriction**: Commands run in a designated directory - **Timeout**: Long-running commands are automatically terminated - **Dangerous command blocking**: Commands like `rm -rf /`, `sudo`, and similar are blocked - **Confirmation required**: Shell commands require approval before execution (you can set "always approve" per tool) ## Memory Privacy All memory files are plaintext markdown stored locally: ``` ~/.foxl/workspace/ SOUL.md # Agent personality USER.md # Your preferences MEMORY.md # General knowledge memory/ # Daily summaries ``` You can read, edit, or delete any file at any time. There is no encrypted or hidden memory - what you see is exactly what the agent knows. ## Network Security - **Localhost only**: The agent server listens only on localhost. It is not accessible from other devices on your network. - **Connection token**: The web dashboard connects via a random token generated at startup. - **No external telemetry**: Foxl does not send usage data, crash reports, or analytics to any server. ## Cloud Relay The relay server at relay.foxl.ai handles: - **Authentication**: Sign in with Google, Apple, or email - **Model routing**: Routes API calls to AI providers (AWS Bedrock) - **Credit billing**: Tracks credit usage for your account The relay does **not** store your conversations, memory, files, or any personal data. When using the Desktop Relay for remote access, all messages are end-to-end encrypted (ECDH P-256 + AES-256-GCM). ## Bring Your Own Key When you use your own API keys (Settings > Providers), requests go directly from your machine to the AI provider. The Foxl relay is not involved. No credits are consumed. Supported providers for BYOK: - Anthropic (Claude API direct) - OpenAI (GPT-4, etc.) - Google (Gemini) - Ollama (local models, completely offline) ## API Key Storage API keys are stored locally in the desktop app's configuration. They are never sent to Foxl servers - only to the respective AI provider when making API calls. For maximum privacy, use Ollama with local models. Your conversations never leave your machine, no API calls are made, and no credits are consumed. --- Skills are installable capability packages that extend what Foxl can do. Each skill is a `SKILL.md` file containing instructions, tool requirements, and domain expertise that the agent loads on demand. ## How Skills Work Skills use a lazy-loading pattern for efficiency: 1. Only skill names and short descriptions are included in the system prompt 2. When the agent decides a skill is relevant, it reads the full `SKILL.md` file 3. The skill's instructions guide the agent through the task This keeps the agent fast while providing deep expertise when needed. The skill library is versioned in the [foxl-ai/skills](https://github.com/foxl-ai/skills) repo and synced into `~/.foxl/skills/` on launch. You can enable, disable, or customize any skill from the Skills page in the app, and add your own local skills by dropping a `SKILL.md` file in the skills directory. ## Skill Categories Document processors, communication skills, and coding helpers all live in one flat directory. The groupings below describe intent, not filesystem layout. ### Productivity and documents | Skill | Default | Description | |-------|:-------:|-------------| | **github** | on | Interact with GitHub using the `gh` CLI for issues, PRs, and CI runs | | **notion** | on | Create and manage Notion pages, databases, and blocks via API | | **obsidian** | on | Work with Obsidian vaults and notes using `obsidian-cli` | | **gws** | on | Google Workspace CLI - Gmail, Calendar, Drive, Sheets, Docs, Chat, Tasks, Meet | | **outlook** | on | Outlook email, calendar, and Microsoft To-Do via Microsoft Graph API | | **outlook-web** | on | Legacy browser-extension Outlook skill (fallback when Graph is unavailable) | | **quip** | on | Manage Amazon Quip documents via REST API | | **himalaya** | off | CLI email client via IMAP/SMTP - list, read, write, reply, search | | **docx** | on | Create, read, edit, or manipulate Word (.docx) documents | | **xlsx** | on | Read, edit, or produce spreadsheets (.xlsx, .xlsm, .csv, .tsv) | | **pptx** | on | Create or edit PowerPoint (.pptx) presentations | | **pdf** | on | Read, extract, merge, split, watermark, fill, or OCR PDF files | ### Media and audio | Skill | Default | Description | |-------|:-------:|-------------| | **spotify** | off | Control Spotify playback and search via terminal | | **spotify-player** | off | Terminal Spotify playback via `spogo` or `spotify_player` | | **sonos** | off | Control Sonos speakers - discover, play, volume, group | | **voice-call** | off | Start voice calls via Twilio, Telnyx, or Plivo | | **sherpa-onnx-tts** | off | Local text-to-speech via sherpa-onnx (offline, no cloud) | | **video-frames** | off | Extract frames or clips from videos using ffmpeg | ### Agent tooling (built-ins as skills) These ship as skills so you can toggle them off to reclaim system-prompt tokens on simpler conversations. | Skill | Default | Description | |-------|:-------:|-------------| | **browser-tool** | on | Browser automation via `agent-browser` - navigate, click, fill, screenshot, extract | | **code-search-tool** | on | Search code with grep / ripgrep for patterns, symbols, and functions | | **exec-tool** | on | Execute shell commands and manage background processes | | **git-tool** | on | Git subcommand shortcuts - status, diff, log, branch, checkout, commit, push, pull | | **web-fetch-tool** | on | Fetch content from URLs - web pages, APIs, online resources | ### Coding assistants | Skill | Default | Description | |-------|:-------:|-------------| | **claude-code** | off | Use the Claude Code CLI with your Claude Pro/Max subscription | | **codex-cli** | off | Use the OpenAI Codex CLI with your ChatGPT subscription | | **gemini-cli** | off | Use the Gemini CLI with your Google AI subscription or API key | | **gemini** | off | Gemini CLI for one-shot Q&A and generation | | **coding-agent** | off | Run Codex CLI, Claude Code, or other coding agents as a background process | | **electron** | off | Automate Electron desktop apps (VS Code, Slack, Discord, Figma, etc.) via CDP | | **skill-creator** | on | Create, edit, optimize, or benchmark skills with eval runs and variance analysis | ### Research and automation | Skill | Default | Description | |-------|:-------:|-------------| | **research-assistant** | on | Help with research tasks and information gathering | | **autoresearch** | off | Autonomous ML research loop that edits `train.py`, runs experiments, keeps improvements | | **tmux** | off | Remote-control tmux sessions for interactive CLIs | ### Utility | Skill | Default | Description | |-------|:-------:|-------------| | **weather** | on | Get current weather and forecasts (no API key required) | | **healthcheck** | off | Host security hardening and risk-tolerance configuration | ## Browsing and Installing Skills Open the **Skills** page from the sidebar to see every skill shipped with Foxl plus anything you've added locally. Each skill row shows: - Name and description - Enable / disable toggle (flips the default above) - Required tools, binaries, or credentials - Stored environment variables (API keys) - editable from the Integrations page Only third-party, SaaS-shaped skills surface on the **Integrations** page (github, notion, obsidian, gws, outlook, quip, himalaya, spotify, sonos, voice-call, weather). The Skills page remains the full catalog. Some skills require external tools. For example, `spotify-player` needs the `spogo` or `spotify_player` binary on PATH, and `sherpa-onnx-tts` needs the sherpa-onnx runtime. The Skills page shows compatibility status per skill and flags missing dependencies inline. ## Creating Custom Skills Create your own skill by adding a `SKILL.md` file: ``` ~/.foxl/skills/my-skill/SKILL.md ``` The file uses YAML frontmatter for metadata and markdown for instructions: ```markdown --- name: my-skill description: Short description of what this skill does enabled: true requires: env: [MY_SERVICE_API_KEY] bins: [my-cli] --- ## Instructions Tell the agent how to use this skill... ``` `requires.env` entries become editable from the Integrations page, so API keys are managed from the UI rather than shell profiles. `requires.bins` get a PATH check at load time, with inline setup hints when a binary is missing. The agent will discover your skill automatically on next conversation. --- Foxl can spawn sub-agents - independent AI sessions that work on tasks in parallel. This lets the main agent delegate work and manage multiple operations simultaneously. ## How Sub-agents Work When the agent encounters a complex task that benefits from parallel execution, it can: 1. **Spawn** a sub-agent with a specific task and instructions 2. **Monitor** the sub-agent's progress 3. **Collect** results when the sub-agent finishes 4. **Stop** a sub-agent if needed Up to 5 sub-agents can run concurrently. ## Sub-agent Tools | Tool | Description | |------|-------------| | **sessions_spawn** | Create a new sub-agent with a task prompt | | **sessions_status** | Check progress of running sub-agents | | **sessions_stop** | Terminate a running sub-agent | ## Use Cases ### Parallel Research > "Research these 3 competitors and compile a comparison" The agent spawns 3 sub-agents, each researching one competitor simultaneously, then combines the results. ### Multi-file Code Changes > "Refactor the authentication module" The agent spawns sub-agents to work on different files in parallel - one for the login flow, one for session management, one for the API endpoints. ### Background Monitoring > "Keep an eye on this deployment while I work on something else" A sub-agent monitors a deployment in the background while the main conversation continues with other tasks. ## Sub-agent Visibility Sub-agent activity is visible in the **Agent** page in the sidebar. You can see: - Active sub-agents and their tasks - Progress status for each - Resource usage Sub-agents share the same tools and permissions as the main agent. They can read files, run commands, and use the browser - all with the same safety controls. ## Limitations - Maximum 5 concurrent sub-agents - Sub-agents cannot spawn their own sub-agents - Each sub-agent has its own context window (separate from the main conversation) - Sub-agents are available in the desktop app only --- The Foxl desktop agent comes with ~20 built-in tools organized into profiles, plus a few capability-gated tools (like `generate_image`) that register automatically when their credentials are available. The agent selects which tools to load based on the task complexity. Tools are only available in the desktop app. The web app (app.foxl.ai) is chat-only. ## Browser | Tool | Description | |------|-------------| | **browser** | Playwright-based web automation - navigate, click, type, screenshot, extract content | | **browser_extension** | Control your real Chrome tabs via the Chrome extension | ## Code & Files | Tool | Description | |------|-------------| | **file_read** | Read files from your filesystem | | **code_search** | Search across your codebase with ripgrep (regex, file type filters) | | **view_image** | View and analyze images | ## Shell & System | Tool | Description | |------|-------------| | **exec** | Run shell commands (bash, zsh, etc.) - covers `git`, `npm`, `curl`, and arbitrary shell pipelines | | **process** | List, monitor, and kill running processes | | **terminal** | Persistent terminal session for stateful shell workflows | ## Web | Tool | Description | |------|-------------| | **web_fetch** | Fetch web pages and API endpoints | ## Memory | Tool | Description | |------|-------------| | **memory_save** | Save key-value pairs to the SQLite memory database | | **memory_recall** | Search and retrieve from the memory database | | **workspace_memory_save** | Save content to workspace markdown files (USER.md, MEMORY.md) | | **workspace_memory_search** | Search across all workspace markdown files | | **workspace_memory_read** | Read a specific workspace file | | **workspace_memory_edit** | Edit sections within workspace files | ## Scheduling | Tool | Description | |------|-------------| | **schedule** | Create, list, update, delete, and trigger schedules (cron, heartbeat, webhook) | ## Agent | Tool | Description | |------|-------------| | **session_status** | Get current date/time, timezone, and session info | | **sessions_spawn** | Spawn an autonomous sub-agent for a parallel task (max 5 concurrent) | | **sessions_status** | Check sub-agent progress | | **sessions_stop** | Stop a running sub-agent | ## Integrations Integration tools are only available after you connect the corresponding account in Settings - Integrations. | Tool | Actions | Description | |------|---------|-------------| | **outlook** | 21 actions | Email (inbox, read, send, reply, forward, search, folders, drafts, attachments, contacts, move, categories, update), Calendar (view, meeting, availability, room booking, search, shared list), To-Do (lists, tasks, checklist) via Microsoft Graph API | | **slack** | 16 actions | search_messages, whoami, get_recent_messages, channels_list, conversations_history/replies/add_message/open/members, check_replies_batch, users_lookup/profile_get, attachment_get_data, reactions_add/remove, file_upload | These tools use OAuth user tokens - they act as you, not as a bot. Connect via Settings - Integrations - Connect. ## Channels | Tool | Description | |------|-------------| | **channel_send** | Send messages to connected channels (Discord, Slack, Telegram, etc.) | ## Media | Tool | Description | |------|-------------| | **generate_image** | Generate or edit PNG images with `gpt-image-2` through your ChatGPT Plus/Pro subscription. Pass `inputImages` paths to edit or compose from existing images; omit for pure text-to-image. Auto-saved under `data/workspace/generated/generated--.png`. | **`generate_image` uses your ChatGPT subscription, not an OpenAI API key.** The tool only registers when an OAuth credential file is found at `~/.codex/auth.json`, `~/.chatgpt-local/auth.json`, or the path set by `CODEX_HOME` / `CHATGPT_LOCAL_HOME`. No additional billing outside your existing $20/month plan. ### Image editing and composition Pass one or more existing image paths as `inputImages` to switch from text-to-image into edit / compose mode. When you drag images into the chat, Foxl auto-persists them to `data/workspace/attachments/` and injects the absolute paths into your message, so the agent can reference them without base64 round-tripping through the model's tool-call args. Examples the agent can drive end-to-end: | Prompt | What the agent does | |--------|--------------------| | "이 사진 만화풍으로 바꿔줘" (attach a photo) | Calls `generate_image({ prompt: "convert to watercolor anime style", inputImages: [""] })` | | "이 두 이미지 합쳐서 하나로" (attach 2+ photos) | Calls `generate_image({ prompt: "compose both subjects into one scene", inputImages: ["", ""] })` | | "blog hero: a cozy cafe at dusk, 1536x1024" | Calls `generate_image({ prompt: "...", size: "1536x1024" })` | Up to 10 input images per call. Output PNG lives at a date-stamped filename with a slug derived from the prompt, in a `generated/` subfolder to keep your workspace root clean. ## Tool Profiles Foxl uses tool profiles to control how many tools are loaded, saving tokens in the system prompt: | Profile | Tools | Token Cost | |---------|-------|------------| | **Minimal** | ~8 tools (memory + workspace) | ~1,600 tokens | | **Default** | ~12 tools (+ file, exec, channels, media) | ~2,400 tokens | | **Standard** | ~13 tools (+ web, code search) | ~2,600 tokens | | **Full** | ~19 tools (all including browser, schedule, agents, media) | ~3,800 tokens | The agent runs in **Full** profile by default. You can switch profiles in Settings to save tokens on simpler tasks. `generate_image` lives in the `media` category and is included in Default, Standard, and Full profiles; Minimal omits it to preserve its token budget. Git operations route through `exec` (e.g. `exec git status`, `exec git push`). There is no dedicated `git` tool - piping and custom flags work better from `exec` anyway, and the exec approval path still gates destructive operations. ## Skills Beyond built-in tools, Foxl supports **skills** - installable capability packages that extend what the agent can do. See [Skills](/docs/skills) for the full catalog. --- ## Desktop App ### App won't open on macOS Right-click the app in Applications and select **Open**. macOS Gatekeeper may block first launch. Foxl is notarized by Apple (Team ID: B47A25FR9P). ### "Node.js not found" error Foxl requires Node.js 22 or later. Install from [nodejs.org](https://nodejs.org) or via Homebrew: ```bash brew install node@22 ``` ### Agent not responding 1. Check the **Logs** page in the sidebar for errors 2. Try restarting the desktop app 3. Verify your internet connection (needed for cloud model access) 4. If using BYOK, check that your API key is valid in Settings > Providers ### High memory usage The agent runs a Node.js process. If memory usage is high: 1. Close unused conversations 2. Restart the app to clear agent state 3. Check for long-running background processes in the **Agent** page ## Web App (app.foxl.ai) ### Can't sign in - Try a different sign-in method (Google, Apple, or email magic link) - Clear browser cookies for app.foxl.ai and try again - Check that your browser allows third-party cookies (needed for OAuth) ### "Desktop Offline" but desktop app is running 1. Check that both devices are connected to the internet 2. Verify the pairing in desktop Settings > Relay 3. Try disconnecting and re-pairing with a new 6-character code 4. Check if a firewall or VPN is blocking WebSocket connections ### Conversations not loading Web app conversations are stored in localStorage. If they disappeared: - Check if you cleared browser data - Try a different browser to see if conversations are browser-specific - Conversations in relay mode are stored in the browser, not synced across devices ### Slow responses - Check your internet connection - Try switching to a faster model (Haiku 4.5 is fastest) - Check [status.foxl.ai](https://status.foxl.ai) for service status ## Chrome Extension ### Extension shows "Disconnected" The extension connects to the desktop agent via localhost WebSocket: 1. Make sure the desktop app is running 2. Check `chrome://extensions` for any error messages 3. Reload the extension (toggle off/on in chrome://extensions) ### Agent can't see page content Some pages block content extraction: - Pages with strict CSP (Content Security Policy) - CAPTCHAs and bot protection - Dynamic SPAs that load content after initial render Try refreshing the page or using the Playwright-based `browser` tool as a fallback. ### Extension interfering with normal browsing The extension is passive by default - it only activates when the agent requests it. If you experience issues: 1. Disable the extension in `chrome://extensions` 2. Use only when needed with the desktop agent ### Windows: SmartScreen warning on first launch Foxl for Windows is currently self-signed. When you first run it, Windows SmartScreen may show a warning. Click **More info** then **Run anyway**. This is safe. ### Windows: "Node.js not found" error Install Node.js 22+ from [nodejs.org](https://nodejs.org). If you used a portable Node.js install, make sure the `node` binary is in your system PATH. ### Windows: PowerShell terminal not working Foxl prefers PowerShell 7+ (`pwsh.exe`). If not available, it falls back to Windows PowerShell. Install PowerShell 7: ```powershell winget install Microsoft.PowerShell ``` ## Credits and Billing ### Credits show as 0 after signup Credits may take a moment to sync. Try: 1. Refresh the page 2. Sign out and sign back in 3. Wait 30 seconds and check again ### "Rate limit exceeded" You've hit the daily request limit: - Free: 200/day - Pro: 2,000/day - Ultra: 10,000/day Wait until midnight UTC or upgrade your plan. ### Charged but credits not updated Contact [support@foxl.ai](mailto:support@foxl.ai) with your account email and transaction ID. ## Scheduling ### Schedules not running 1. Desktop app must be running for schedules to execute 2. Check the Schedules page for any failed runs 3. Verify the cron expression is correct 4. Check Logs for any errors during execution ### Schedule ran but produced no output - The scheduled task may have failed silently - Check Logs for the specific schedule execution - Try running the task manually first to verify it works ## Getting Help - **Discord**: [Join our community](https://discord.gg/6J53VyV2Fy) - use `/ask` for instant AI answers, or create a private support ticket - **Email**: [support@foxl.ai](mailto:support@foxl.ai) for billing and account issues - **GitHub**: [Report bugs](https://github.com/foxl-ai/foxl/issues) for the desktop app --- The workspace is a folder of markdown files that serve as the agent's persistent knowledge base. Unlike the SQLite database (structured key-value memory), workspace files are human-readable documents you can browse and edit directly. ## Workspace Structure ``` ~/.foxl/workspace/ SOUL.md # Agent personality and behavior rules USER.md # Information about you MEMORY.md # General knowledge and notes AGENTS.md # Sub-agent configurations TOOLS.md # Tool usage notes and preferences HEARTBEAT.md # Heartbeat schedule configuration BOOTSTRAP.md # Initial setup instructions memory/ 2026-03-15.md # Daily conversation summary 2026-03-16.md # Daily conversation summary ... ``` ## Core Files | File | Purpose | |------|---------| | **SOUL.md** | Agent personality, behavior rules, and system prompt. The most important customization file. | | **USER.md** | Information about you - the agent learns and updates this over time. | | **MEMORY.md** | General knowledge, notes, and reference material. | | **AGENTS.md** | Sub-agent configurations. | | **TOOLS.md** | Tool usage notes and preferences. | | **HEARTBEAT.md** | Heartbeat schedule configuration. | | **BOOTSTRAP.md** | Initial setup instructions for new workspaces. | | **memory/YYYY-MM-DD.md** | Auto-generated daily conversation summaries. | For detailed descriptions of each file - including how to customize SOUL.md as your system prompt and what to put in USER.md - see the [Memory guide](/docs/memory). ## Browsing the Workspace ### From the Dashboard Open the **Workspace** page in the sidebar to browse all files in a web-based editor. You can read and edit files directly. ### From the Filesystem Open any workspace file with your preferred text editor: ```bash # macOS / Linux code ~/.foxl/workspace/USER.md # VS Code nano ~/.foxl/workspace/SOUL.md # Terminal open ~/.foxl/workspace/ # Finder # Windows (PowerShell) code $env:USERPROFILE\.foxl\workspace\USER.md explorer $env:USERPROFILE\.foxl\workspace ``` ### Through Conversation Ask the agent about its workspace: - "What's in your SOUL.md?" - "Show me my USER.md" - "What did we discuss yesterday?" (reads daily journal) ## Workspace Tools The agent uses these tools to interact with the workspace: | Tool | Description | |------|-------------| | **workspace_memory_save** | Add content to a workspace file | | **workspace_memory_read** | Read a workspace file | | **workspace_memory_search** | Search across all workspace files | | **workspace_memory_edit** | Edit sections of a workspace file | ## Privacy All workspace files are local. They are never uploaded to Foxl servers or included in API calls to AI providers (unless the agent explicitly reads them into the conversation context).