# Foxora — complete knowledgebase > Foxora is the first L5 autonomous multi-agent system. Describe an outcome in plain words; a crew of AI specialists plans it, builds it, checks its own work, and delivers the finished thing — with permanent shared memory. It runs as a desktop app, in the web, and as a CLI. Built by xBesh Labs, LLC. Free to start, no credit card, no separate AI accounts. > This single file is the entire Foxora platform — the marketing site and the full product documentation — concatenated as Markdown. Hand it to an AI model as the knowledgebase for answering anything about Foxora. # Part 1 — Site --- source: https://foxora.ai/ title: Foxora — your AI workforce --- Eyebrow: The first L5 autonomous multi-agent system. Headline: Build your team. On foxora. A team that never sleeps and never forgets. Just describe the outcome — a crew of AI specialists researches, builds, verifies, and hands you work that's actually finished, not a draft you have to fix. ## Why Foxora — autonomy has levels AI tools help you work; Foxora works for you. Borrowed from the self-driving levels: L1 autocomplete, L2 copilot (you steer), L3 single agent (you watch), L4 crew (a human gates each step), L5 workforce — you give the goal and it delivers the finished outcome. Foxora is built L5-first, with a full audit trail so autonomy never means opacity. ## How it works One sentence in, a finished thing out. A planner turns your goal into a work plan, specialists run the pieces in parallel, a checker challenges everything, and the result comes back done — with its memory updated. ## The crew A specialist for every job (researcher, coder, reasoner, verifier, scout, tester, writer, designer, data, vision, web-search, devops, security, integrator, and more) — and any role you invent. Roles run in parallel, nothing reaches you before the checker signs off, and each specialist routes to the level of AI its work deserves. ## Queue & delegation Stack up tasks like a to-do list. The planner assigns each to the right crew, delegates across agents and tools, and runs it in the cloud — laptop optional. ## Memory (the Den) It remembers like a colleague, not a chatbot. Your preferences, projects, and rules — explained once, kept for good. Facts settle through four layers (raw, episodic, semantic, relational), and every memory carries a receipt: ask "why do you think that?" and it shows you where it learned it. The Den lives on your machine. ## Tell it once Sessions and memory are one shared record across desktop, web, and CLI. Start anywhere, continue anywhere — never paste the same context twice. ## Skills Done-for-you playbooks (launch a product, run a newsletter, sort a backlog, audit a codebase) — plus a Skill Builder to teach Foxora your own way of doing things. A skill is a procedure with tools and scripts attached. ## Your workforce Build departments, crews, and agents like a real company. Or describe what you need and the AI builder drafts the whole team. You stay the boss. ## 1,000+ plugins Connected to the apps you already use — Gmail, GitHub, Slack, Stripe, Linear, Notion, and more, one click each. OAuth tokens are held by Composio (the connector-auth layer trusted by teams like Anthropic and OpenAI), never on Foxora's servers. Revoke anything, any time. ## Built-in IDE A full code studio inside: tabs, files, git (stage, commit, PR), and a live Stage where agents open terminals and browsers. Multiple projects open at once. If you don't code, you never see this screen. ## Voice Talk to your crew like a chief of staff. Ask what happened overnight, order what ships next — it answers out loud, queues the work, and reports back. ## Everywhere The same crew and memory in a window (Desktop), a browser (Web, app.foxora.ai), or a terminal (CLI). One account, everywhere. ## Overnight (cloud agents) Scheduled crews run in the cloud — they don't need your laptop open, and everything they learn lands in the same memory. ## No API keys, ever Your plan includes the intelligence, metered in simple credits like minutes on a phone plan. Every request routes to the right level of AI (Fast, Premium, Max) — no provider secrets on your machine; sign-in is PKCE end to end. ## Your work stays yours The desktop engine runs on your machine; your files never have to leave, and nothing trains on them. Every action is logged and rewindable. Signed builds, public releases, and an install script you can read before you run it. ## FAQ (summary) - Do I need to code? No — talk in plain words; builders get a code studio, everyone else never sees it. - What is L5? Full autonomy: you give the destination, it drives; every action logged. - Mistakes? A checker validates before you see it; every change is a reviewable diff; stop/rewind anytime. - AI accounts / API keys? None — the plan includes the intelligence, metered in credits. - Where do OAuth tokens live? In Composio's vault, never on Foxora's servers; revoke anytime. - Where does my work live? On your machine (desktop); cloud work runs in inspectable isolated sessions; PKCE sign-in. --- source: https://foxora.ai/pricing title: Foxora — Pricing --- Simple, credit-based pricing for your AI workforce. One plan covers the whole crew — every model, every surface. No API keys, no per-provider bills, no surprises. Start free, then Starter, Pro, or Max. ## Plans ### Free — Free Kick the tires — no card required. Monthly credits: 200. Includes: - 200 credits / month - Fast crew (500K tokens / mo) - Memory Den included - 5 image analyses / month - Community support ### Starter — $29/mo, or $24/mo billed annually ($290/yr) For individuals and small projects. Monthly credits: 2,000. Includes: - 2,000 credits / month - Fast (25M) + Premium (2.5M) crews - 100 web searches / month - 100 image analyses / month - Voice in & out - Cloud agents — 50 runs / month - Scheduled tasks — up to 5 - 1M embedding tokens / month - Email support ### Pro — $59/mo, or $49/mo billed annually ($590/yr) (recommended) For professionals and growing teams. Monthly credits: 5,000. Includes: - Everything in Starter, plus: - 5,000 credits / month - Fast (50M) + Premium (5M) crews - 500 web searches / month - 500 image analyses / month - Cloud agents — 500 runs / month - Scheduled tasks — up to 50 - 10M embedding tokens / month - Priority support ### Max — $199/mo, or $166/mo billed annually ($1,990/yr) Maximum power for heavy users and agencies. Monthly credits: 20,000. Includes: - Everything in Pro, plus: - 20,000 credits / month - Max crew — Opus 4.8 / GPT-5 Pro (4M) - Fast (60M) + Premium (7M) crews - 2,000 web searches / month - 2,000 image analyses / month - Cloud agents — 5,000 runs / month - Scheduled tasks — up to 500 - 50M embedding tokens / month - Partner program Annual billing includes 2 months free. Credits meter everything like minutes on a phone plan — one grant per month, spent across the whole crew. Full side-by-side feature comparison is on the pricing page. --- source: https://foxora.ai/download title: Foxora — Download --- Get Foxora on your desktop, in your browser, or in your terminal. ## Desktop app macOS (Apple Silicon & Intel, signed and auto-updating) and Windows 10/11. Linux desktop is coming soon. Builds are signed and update themselves from the public releases repo. ## Web app Skip the install entirely — open app.foxora.ai in any browser. Same crew, same memory, same account. ## macOS installer / updater One command installs or replaces Foxora Desktop and then provisions Foxora Core: `curl -fsSL https://foxora.ai/install.sh | sh`. It preserves your account, projects, sessions, and Memory Den. ## CLI The CLI has its own installer: `curl -fsSL https://foxora.ai/install-cli.sh | sh` on macOS/Linux, or `irm https://foxora.ai/install.ps1 | iex` on Windows. Three steps to start: install (or open the web app) → sign in at app.foxora.ai → describe a goal. No API keys, no separate AI accounts. --- source: https://foxora.ai/cli title: Foxora — CLI --- A crew of agents in your terminal. Install: `curl -fsSL https://foxora.ai/install-cli.sh | sh` (macOS/Linux) or `irm https://foxora.ai/install.ps1 | iex` (Windows). The CLI installs the same engine as the desktop app; the runtime provisions on first run. ## Command reference (examples) - `foxora ""` — state a goal in quotes; the crew ships it - `foxora crew` — see who's on the bench and who's working - `foxora queue add ""` — stack work for the cloud - `foxora skills` — list the playbooks, or build your own - `foxora connect gmail` — one-click plugin auth (1,000+ apps via Composio) - `foxora recall ""` — search shared memory, receipts included - `foxora voice` — talk instead of type - `foxora org --tree` — departments, crews, agents ## Built for pipelines Clean JSON with `--json`, honest exit codes, streaming output. Works in ssh, docker, CI, cron, Makefiles, and git hooks. One account, one memory — the same crew as desktop and web. --- source: https://foxora.ai/status title: Foxora — Status --- Live status of every Foxora service. Health is checked directly from our own servers (no third-party monitoring): the web app (app.foxora.ai), AI gateway (api.foxora.ai), cloud engine (engine.foxora.ai), auth & database (Supabase), docs, and the website. Each service shows its current state (operational / degraded / down) and response time, refreshed every minute. Contact: status@foxora.ai. --- source: https://foxora.ai/about title: Foxora — About --- Foxora is the operating system for AI agents, a product of xBesh Labs, LLC — a Delaware limited liability company registered at 8 The Green, Dover, Delaware, United States 19901. Mission: make AI agents practical, observable, and production-ready — real systems that run your business, not demos. State the goal; ship the thing. Contact: hello@foxora.ai (partnerships, media, general inquiries). --- source: https://foxora.ai/brand title: Foxora — Brand --- The Foxora brand kit. - Logo: the app-icon tile (dark rounded square holding the two-tone fox) plus the "foxora" wordmark, with SVG downloads. Keep the icon and wordmark together or use the icon alone. - Color: espresso #171412 (background), cream #f5f2ec (ink), and pastel accents — peach, rose, lavender, sage. - Typography: Cal Sans (display), Inter (body), JetBrains Mono (code). - Do: give the mark clear space; use the espresso or cream background; write "Foxora" with a capital F. - Don't: recolor, stretch, rotate, or add effects; place it on a busy background; misspell it ("foXora", "Foxura"). Brand questions: press@foxora.ai. --- source: https://foxora.ai/privacy title: Foxora — Privacy Policy --- We take your privacy seriously. This policy explains exactly what data Foxora collects, why we collect it, how we protect it, and the choices you have. ## 1. Overview xBesh Labs, LLC ("xBesh Labs", "we", "us", or "our") is the legal entity behind Foxora AI. We operate the website at foxora.ai and the Foxora AI platform, including its API, agent runtime, dashboard, and all related services (collectively, the "Service"). xBesh Labs, LLC is incorporated in Delaware, United States. Our registered address is 8 The Green, Dover, Delaware, United States 19901. This Privacy Policy describes how we collect, process, store, share, and protect personal information when you use the Service, and explains the choices available to you regarding your personal data. Plain language summary: We only collect what we need to run the product. We do not sell your data. We give you full control to access, update, or delete your information at any time. ## 2. Data we collect Account & identity — name, email, and password hash when you register; profile settings and preferences; billing name, address, and payment metadata (card last four, expiry — full card numbers are never stored by us, handled exclusively by Stripe); company name and role if provided. Product usage — API requests, model calls, token counts, latency, and cost records; feature flags; agent configurations you create; support tickets and communications. Technical & device — IP address, browser, OS, and device type; log data including error traces, request IDs, and timestamps; session tokens and authentication events; referral source and UTM parameters. Content you provide — prompts, inputs, and outputs processed through the Foxora API (used solely to deliver the service; not used for model training); files or data you upload for analysis features. ## 3. How we use data We use the information we collect to: - Provision, operate, and maintain the Service and its features - Process billing, manage subscriptions, and prevent fraud - Enforce plan limits, rate limits, and acceptable-use policies - Send transactional emails (confirmation, invoices, password reset, usage alerts) - Provide customer support and resolve technical issues - Monitor and improve reliability, performance, and security - Generate aggregated, anonymized analytics about service usage - Comply with legal obligations and respond to lawful requests We do not use your prompts, agent outputs, or API request content to train any machine learning model — ours or any third party’s. ## 4. Data sharing We do not sell, rent, or trade your personal information. We may share data with third parties only in these limited circumstances: Service providers — vendors who help us operate the Service, including Supabase (database & auth), Stripe (payments), Postmark (email), Sentry (error monitoring), Upstash (caching), and Railway (infrastructure), under data processing agreements. AI model providers — when you make API requests, your inputs are routed through our gateway to third-party model providers (e.g. Google, OpenAI) to generate responses. We route through our gateway so providers never receive your Foxora credentials or account identity. Legal requirements — we may disclose information if required by law, court order, or to protect the rights, property, or safety of xBesh Labs, LLC, our users, or the public. Business transfers — in a merger, acquisition, or sale of assets, user data may be transferred. We will notify users via email and a prominent notice before any such transfer. ## 5. Retention & security We retain personal data for as long as your account is active and as necessary to provide the Service, meet legal obligations, resolve disputes, and enforce agreements. - Account data — retained while active and for up to 90 days after deletion, then permanently purged - API usage logs — up to 13 months for billing reconciliation and abuse detection - Payment records — 7 years, as required by financial regulations - Support communications — 3 years Security protections include TLS/HTTPS for data in transit, AES-256 encryption for sensitive values at rest, row-level security and role-based database access, multi-factor authentication for infrastructure access, and regular security reviews and dependency audits. ## 6. Cookies & tracking We use essential cookies and browser storage to operate the Service — session and authentication state (Supabase Auth), dashboard theme preference (localStorage), affiliate tracking cookies (30-day window), and CSRF protection tokens. We do not run third-party advertising networks or cross-site behavioral tracking. You can manage cookies in your browser settings, though disabling essential cookies will prevent login. ## 7. Your rights Depending on your jurisdiction, you may have the following rights: - Access — request a copy of the personal data we hold about you - Correction — update inaccurate profile information via dashboard settings - Deletion — request permanent deletion of your account and data - Portability — export your usage data and account information - Restriction — object to certain processing activities - Opt-out of marketing — unsubscribe from non-transactional emails at any time To exercise these rights, contact us at privacy@foxora.ai or use your dashboard settings. We respond to all requests within 30 days. ## 8. Children The Service is not directed to individuals under 16. We do not knowingly collect personal information from children. If we learn that a child has provided us with personal data, we will delete it promptly. If you believe a child has provided us with data, contact privacy@foxora.ai. ## 9. Policy changes We may update this Privacy Policy from time to time. When we make material changes, we will notify you by email and update the "Last updated" date. Continued use of the Service after notification constitutes acceptance of the updated policy. ## 10. Contact us For privacy-related questions, data requests, or to report a concern, contact us at privacy@foxora.ai. --- source: https://foxora.ai/terms title: Foxora — Terms of Service --- By accessing or using Foxora, you agree to be bound by these terms. Please read them carefully before using the Service. ## 1. Agreement to terms These Terms of Service ("Terms") constitute a legally binding agreement between you ("User", "you") and xBesh Labs, LLC, a Delaware limited liability company ("xBesh Labs", "Company", "we", "us"), the legal entity operating the Foxora AI platform, API, dashboard, and all associated services (the "Service"). xBesh Labs, LLC is registered at 8 The Green, Dover, Delaware, United States 19901. By creating an account, accessing the API, or otherwise using the Service, you acknowledge that you have read, understood, and agree to these Terms and our Privacy Policy. If you are using the Service on behalf of an organization, you represent that you have authority to bind that organization. If you do not agree, do not create an account or use the Service. ## 2. The Service Foxora provides an AI agent platform including a web dashboard, REST API gateway, agent orchestration runtime, and developer tools. The Service allows users to send requests to AI language models through the Foxora API gateway; configure, deploy, and monitor agents; access usage analytics, billing, and team administration; and integrate Foxora capabilities into third-party applications via API keys. We reserve the right to modify, suspend, or discontinue any aspect of the Service at any time, with reasonable notice where possible. We are not liable for any modification, suspension, or discontinuation of the Service. ## 3. Accounts & registration To access the Service, you must register for an account and provide accurate, complete, and current information. You are responsible for maintaining the confidentiality of your credentials (including API keys), all activity under your account, promptly notifying us of any unauthorized access, ensuring only authorized individuals access your account, and keeping your account information accurate. You must be at least 16 years old to create an account. Business accounts must be operated by individuals authorized to enter contracts on behalf of their organization. ## 4. Acceptable use You agree to use the Service only for lawful purposes and in accordance with these Terms. You must not: - Generate, distribute, or facilitate illegal, harmful, or abusive content - Violate any applicable local, national, or international law or regulation - Attempt to circumvent rate limits, plan restrictions, or security controls - Reverse engineer, decompile, or extract source code from the Service - Scrape, crawl, or extract data from the Service beyond normal API usage - Resell, sublicense, or white-label the Service without a written agreement - Impersonate any person or entity or misrepresent your affiliation - Transmit malware, viruses, or disruptive code through the Service - Impose unreasonable load on the infrastructure - Generate spam, phishing content, or deceptive material We reserve the right to investigate and take appropriate action, including suspending or terminating accounts that violate these policies. ## 5. Billing & plans Paid plans are billed on a recurring basis (monthly or annual) via Stripe. Fees are non-refundable except as required by applicable law or at our sole discretion. Subscriptions automatically renew at the end of each billing period unless you cancel before the renewal date; cancellation takes effect at the end of the current paid period. Each plan includes defined request quotas, premium budgets, and feature access. If you exceed limits, AI requests will be rejected unless you have enabled on-demand billing or hold wallet credits. We may change pricing with at least 30 days’ advance notice, taking effect at the start of your next billing cycle. We do not offer refunds for unused portions of a subscription period, partially used premium budgets, or topup wallet credits; exceptions may be made at our discretion for billing errors. ## 6. API usage - API keys must be kept confidential and not committed to version control or exposed in client-side code - You are responsible for all API usage billed to your account, whether authorized or not - Rate limits apply per plan tier and are enforced by the gateway - We may throttle or block API access that appears abusive or violates these Terms - You agree not to use the API to build competing AI gateway or proxy services If you suspect unauthorized use of your API key, revoke it immediately from your dashboard and contact security@foxora.ai. ## 7. Intellectual property The Service, including its software, design, trademarks, and documentation, is owned by xBesh Labs, LLC and protected by intellectual property laws. The brand name Foxora AI and associated marks are trademarks of xBesh Labs, LLC. You retain ownership of any content, data, or configurations you create through the Service. By using the Service, you grant xBesh Labs, LLC a limited license to process and transmit your content solely to provide the Service to you. Outputs generated by AI models through the Foxora API are subject to the terms of the underlying model providers. xBesh Labs, LLC makes no ownership claims over AI-generated outputs delivered to you. ## 8. Warranties & disclaimers THE SERVICE IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. To the fullest extent permitted by law, xBesh Labs, LLC disclaims all warranties including fitness for a particular purpose or merchantability; uninterrupted, timely, secure, or error-free operation; accuracy, reliability, or completeness of AI-generated outputs; and that any defects will be corrected. AI language model outputs may be inaccurate, incomplete, or harmful. You are responsible for reviewing and validating any AI-generated content before acting on it. ## 9. Limitation of liability To the maximum extent permitted by applicable law, in no event shall xBesh Labs, LLC be liable for any indirect, incidental, special, consequential, or punitive damages; loss of profits, revenue, data, or business opportunities; damages from unauthorized access to your data; damages from reliance on AI-generated outputs; or service outages and performance degradation. The total aggregate liability of xBesh Labs, LLC shall not exceed the greater of $100 USD or the amount you paid to xBesh Labs, LLC in the twelve months preceding the claim. ## 10. Termination You may delete your account at any time from dashboard settings. We may suspend or terminate accounts that violate these Terms, with or without notice depending on severity, or for non-payment after reasonable notice. Upon termination, your right to use the Service ceases immediately, and we will retain data for the period described in our Privacy Policy. Sections that by their nature should survive termination (intellectual property, warranty disclaimers, limitation of liability, and governing law) will survive. ## 11. Governing law & disputes These Terms are governed by the laws of the State of Delaware, United States, without regard to conflict of law principles. Any dispute shall first be attempted through good-faith negotiation, and thereafter through binding arbitration on an individual basis in Delaware, waiving any right to a class action. Nothing prevents either party from seeking injunctive or other equitable relief in a court of competent jurisdiction in Delaware where necessary to protect intellectual property or confidential information. ## 12. Contact For legal notices, compliance requests, or contract inquiries, write to legal@foxora.ai. --- source: https://foxora.ai/cookies title: Foxora — Cookie Policy --- This policy explains how and why Foxora uses cookies and similar tracking technologies across our website and platform. ## 1. What are cookies Cookies are small text files placed on your device by websites you visit. They are widely used to make websites work efficiently and to provide reporting information. xBesh Labs, LLC (operating as Foxora AI) uses cookies and similar storage mechanisms (such as localStorage and sessionStorage) for the purposes described below. ## 2. Essential cookies Essential cookies are required for the Service to function. Without them, login, session management, and secure account access are not possible. These cannot be disabled. - FoxoraAuth — Supabase auth session — Session - FoxoraRefresh — session renewal — 1 year - FoxoraTheme — dashboard color theme — Persistent - FoxoraBotProtection — Cloudflare bot protection — 30 min ## 3. Preference storage We store lightweight UI preferences in your browser’s localStorage to improve your experience across visits, including your theme selection. These values are stored locally on your device and are not transmitted to our servers. ## 4. Analytics We collect anonymized usage metrics to understand product performance and reliability. This data is aggregated and cannot be tied to an individual user. We do not use third-party behavioral advertising networks or cross-site tracking. - Page visit counts and navigation patterns (anonymized) - Feature usage rates and error frequencies - Performance timing data to detect degradation ## 5. Affiliate tracking When you arrive via a Foxora affiliate referral link (e.g. foxora.ai?ref=CODE), we store a tracking cookie for 30 days to attribute any resulting conversion to the referring affiliate partner. This cookie records the affiliate referral code, a hashed visitor ID for deduplication, and UTM parameters from the referral link. This data is used only for commission attribution and is not shared with advertising networks. ## 6. Your control You can manage cookie preferences through your browser settings. Most browsers allow you to refuse new cookies, delete existing cookies, or be notified when new cookies are set. Note: disabling essential cookies (Supabase auth tokens) will prevent you from staying logged in. Preference and analytics cookies can be cleared without affecting core functionality. ## 7. Contact For questions about cookies or tracking on our platform, contact us at privacy@foxora.ai or write to xBesh Labs, LLC, 8 The Green, Dover, Delaware, United States 19901. # Part 2 — Documentation --- source: https://docs.foxora.ai/getting-started/introduction title: Introduction --- # Introduction Foxora is the operating system for AI agents. It bundles a desktop environment, an agent runtime, and a unified API gateway behind one account. ![Introduction — screenshot placeholder](placeholder) ## What you get Foxora is built around three surfaces that share a single account, billing, and data model: - Foxora Desktop — a desktop app that gives every agent its own window, file system, and tools. Read the installation guide. - Cloud agents — long-lived agents that run on Foxora’s infrastructure on a schedule or in response to webhooks. - The Foxora gateway — one HTTP API at https://api.foxora.ai/v1 that routes requests to any model you have access to. See the API reference. ## Who Foxora is for Foxora is built for developers, indie hackers, and teams who want to ship agent-powered features without rebuilding the same plumbing every time: auth, model routing, usage metering, and a UI to run things from. - If you just want a desktop assistant, install Foxora Desktop and start chatting. - If you want to embed Foxora in your own product, use the API gateway. - If you want both, sign in once and switch between them at any time. ## Core concepts ### Account Your Foxora account holds your profile, plan, payment method, and API keys. The same account is used to sign in to the desktop app, the dashboard, and the gateway. ### Plan Plans gate features and set monthly limits. The default plan is free. See Plans & pricing for the full list. ### Agent An agent is a configured assistant: a model, a system prompt, a set of tools, and an optional schedule. Agents can run in Foxora Desktop or as cloud agents. > **New here?** The fastest path is the Quickstart — it walks you from a blank account to a running agent in about five minutes. --- source: https://docs.foxora.ai/getting-started/installation title: Installation --- # Installation Install Foxora Desktop on macOS, Windows, or Linux. The installer brings the desktop app, the agent runtime, and a local SDK for working against the gateway. ![Installation — screenshot placeholder](placeholder) ## System requirements - macOS 12 (Monterey) or newer — Apple Silicon or Intel - Windows 10 / 11, 64-bit - Linux: Ubuntu 22.04 or newer (other distros best-effort) - 4 GB free disk, 8 GB RAM recommended - An internet connection for sign-in and gateway requests ## Install Foxora Pick the tab that matches your operating system. 1. **Install the app** — Choose your platform: **macOS** ```bash # Drag Foxora.app into /Applications, or: brew install --cask foxora ``` **Windows** — Run the downloaded installer. **Linux (AppImage)** — Download the AppImage, make it executable, and run it. **Linux (deb)** — Download the `.deb` package and install it. 2. **Open Foxora for the first time** — macOS may ask you to confirm the first launch. Windows SmartScreen might warn about an unsigned publisher — click **More info** → **Run anyway** until we're fully signed. > **Windows SmartScreen.** We're in the middle of code-signing for Windows. If you hit a SmartScreen warning, verify the installer's SHA-256 hash against the value published alongside the release before running it. 3. **Sign in to your Foxora account** — On first launch the app opens a browser window to `foxora.ai/auth/callback`. After you sign in or sign up, the browser hands the session back to the desktop app via the `foxora://` deep link. No account yet? You can create one during this step — or sign up first at `foxora.ai/signup`. Sign-in works with email + password or a Google account. 4. **Verify the install** — Once you're signed in, the dock and a default agent should appear. From the command line, you can also confirm the bundled CLI is on your path: ```bash foxora --version # → foxora 5.0.3 ``` ## What's next? - Run your first agent — Quickstart - Install the desktop app — Installation - Get an API key — Authentication --- source: https://docs.foxora.ai/getting-started/system-requirements title: System requirements --- # System requirements What Foxora Desktop needs to run, across macOS, Windows, and Linux. ## Supported platforms - macOS 12 (Monterey) or newer — Apple Silicon (arm64) or Intel (x86_64). - Windows 10 / 11, 64-bit. - Linux x64 or arm64 — Ubuntu 22.04+ tested; other distros best-effort. ## Hardware - 8 GB RAM recommended (4 GB minimum). - ~2 GB free disk for the app, runtime, and bundled tooling. - An internet connection for sign-in and gateway requests. ## What the installer brings The installer provisions everything Foxora needs in one pass: the desktop app, the agent runtime and local memory daemon, the Bun runtime, and the Foxora CLI. On Windows it also installs the Microsoft Edge WebView2 and Visual C++ runtimes if they’re missing — and skips them if they’re already present. > **Cloud-backed by default** Agents run against Foxora’s cloud engine through the gateway. Your files, sessions, and memory stay local on your machine — see Where your data lives. --- source: https://docs.foxora.ai/getting-started/quickstart title: Quickstart --- # Quickstart From a blank account to a working agent in about five minutes. We'll send a chat completion via the gateway, then run the same prompt as an agent in Foxora Desktop. ![Quickstart — screenshot placeholder](placeholder) ## 1. Sign in and grab an API key Sign up at [foxora.ai/signup](https://foxora.ai/signup) — or sign in if you already have an account. Open the dashboard at [foxora.ai/dashboard](https://foxora.ai/dashboard), then go to **Settings → API keys → Create new key**. > **Treat the key like a password.** API keys grant access to your plan's usage and spend. Store them in a secret manager — never commit them to git. ## 2. Send your first request The Foxora gateway speaks the same shape as OpenAI's chat completions endpoint, so most existing SDKs work out of the box. Export your key and call it with `curl`: ```bash curl https://api.foxora.ai/v1/chat/completions \ -H "Authorization: Bearer $FOXORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "foxora-ai-fast", "messages": [ { "role": "user", "content": "Say hello in one sentence." } ] }' ``` A successful response (`200 OK`) from `/v1/chat/completions` looks like this: ```json { "id": "chatcmpl-8Yq...", "object": "chat.completion", "model": "foxora-ai-fast", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello!" }, "finish_reason": "stop" } ] } ``` ## 3. Install an SDK locally (optional) The official OpenAI SDK works against Foxora — you only swap the `baseURL`. Install it with whichever package manager you use: ```bash npm install openai # pnpm add openai · yarn add openai · bun add openai ``` Then point the client at the Foxora gateway: ```js import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.FOXORA_API_KEY, baseURL: "https://api.foxora.ai/v1", }); const res = await client.chat.completions.create({ model: "foxora-ai-fast", messages: [{ role: "user", content: "Say hello in one sentence." }], }); console.log(res.choices[0].message.content); ``` ## 4. Run it as a desktop agent Now do the same thing inside Foxora Desktop: 1. Open **Foxora Desktop**. 2. Click **+ New agent** in the dock. 3. Pick a model, paste your system prompt, and click **Run**. 4. Chat with the agent in its own window — it can call tools, edit files in its workspace, and keep running in the background. ![Your first agent running in its own dock window](placeholder) > **Why both?** The gateway is for embedding Foxora in your own product; Foxora Desktop is for using Foxora directly on your machine. Same models, same account, same billing. --- source: https://docs.foxora.ai/getting-started/updating title: Updating Foxora --- # Updating Foxora Foxora keeps itself current. Updates are checked on launch and in the background, and applied with a single click. ## How updates arrive Shortly after launch — and periodically while the app is open — Foxora checks for a new release. When one is available, an update window opens with the new version and a short summary of what changed. ## Installing an update - Click Install & restart. Foxora downloads the update, showing progress. - When it’s ready, the app relaunches into the new version. - Prefer to wait? Dismiss the window — a badge stays in the footer so you can update later. > **Updates are verified** Every update is cryptographically signed and verified before it’s applied, so you only ever run a genuine Foxora build. --- source: https://docs.foxora.ai/getting-started/uninstalling title: Uninstalling --- # Uninstalling How to remove Foxora — and what it leaves behind. ## Remove the app ``` # Quit Foxora, then drag Foxora.app to the Trash, or: brew uninstall --cask foxora ``` Running the installer in uninstall mode removes the desktop app, the CLI, and the Foxora runtime. System runtimes it installed on Windows (WebView2, Visual C++) are kept, since other apps may rely on them. ## Your data Uninstalling the app does not delete your local data folder. Your sessions and memory live in ~/.foxora (%USERPROFILE%\foxora on Windows). Delete that folder to remove everything local; your account and billing live on the server and are managed from the dashboard. > **This can't be undone** Deleting ~/.foxora permanently removes local sessions and your memory den. Export anything you want to keep first from Settings → Data. --- source: https://docs.foxora.ai/accounts/creating-an-account title: Creating an account --- # Creating an account One account signs you in everywhere — Foxora Desktop, the web dashboard, and the gateway. You can create it from the app's sign-in screen or on the web, with email and a password or with Google or GitHub. ## Create your account 1. **Open the sign-in screen** — Launch Foxora Desktop. Until you're signed in, the app shows the sign-in screen. Click **New to Foxora? Create account** to switch into sign-up mode. ![The sign-in screen, switched to sign-up mode.](placeholder) 2. **Choose how you sign up** — You have three options, and you can mix them later: - **Continue with Google** or **Continue with GitHub** — opens your system browser to authorize, then hands the session back to the app. - **Email and password** — enter your full name (optional), email, and a password, then click **Create account**. 3. **Confirm your email** — If email confirmation is required, you'll see a notice: "Account created — check your email to confirm, then sign in." Open the email and click the confirmation link, then return to the app and sign in. Didn't get the email? Check spam, and make sure the address is correct. You can re-trigger a confirmation by attempting to sign in — the app will prompt you if the address is still unconfirmed. ## What your account holds - Profile — your name, email, and avatar. - Plan & billing — your plan, credit balance, and payment method (managed in the web dashboard). - Connections — the apps and model providers you've linked. - Devices — the machines and CLIs authorized against your account. > **Next: get set up** After your first sign-in, Foxora runs a short first-run walkthrough to tailor agents to how you work. --- source: https://docs.foxora.ai/accounts/signing-in title: Signing in --- # Signing in Sign in with email and password, or with Google or GitHub. On the desktop, OAuth is PKCE-native: the app opens your real browser, you authorize there, and the session is handed back securely — no tokens are ever passed inside a URL. ## Sign in with email 1. **Enter your credentials** — On the sign-in screen, type your email and password and click **Sign in**. If your credentials are wrong, a red callout appears at the top of the card explaining what failed. ![Email + password sign-in on the desktop app.](placeholder) ## Sign in with Google or GitHub Click **Continue with Google** or **Continue with GitHub**. Here's what happens under the hood: 1. **The app arms a secure listener** — Foxora opens a one-time loopback listener on a random local port (and registers the `foxora://` deep link as a fallback for a cold start). 2. **Your browser opens to authorize** — The app launches your system browser at the provider's consent screen. The desktop window shows "Finish signing in in your browser — this window will continue automatically." ![The app waits while you authorize in the browser.](placeholder) 3. **The session is handed back** — After you approve, the provider redirects a short-lived code to the loopback listener (or via `foxora://`), the app exchanges it using PKCE, and you land in the app signed in. > **Stays signed in** Foxora keeps your session fresh in the background — it refreshes your token on focus and on a short keep-alive timer so a long agent run never gets interrupted by an expired session. ## Sign out Open Settings (`⌘,` / `Ctrl+,`) → Account and click **Sign out**. This clears the local session and revokes the token mirrored to the local runtime. See Account & devices to manage every place you're signed in. --- source: https://docs.foxora.ai/accounts/resetting-your-password title: Resetting your password --- # Resetting your password Forgot your password? Request a reset link from the sign-in screen. The link opens a secure page where you set a new password — the link itself never carries your session. ## Request a reset link 1. **Open the reset form** — On the sign-in screen, click Forgot password? The card switches to reset mode with a single email field. ![Reset your password — sign-in screen → Forgot password?](placeholder) 2. **Send the link** — Enter the email on your account and click Send reset link. You'll see a "Check your inbox" confirmation with a button to resend if it doesn't arrive. 3. **Set a new password** — Open the email and click the link. It takes you to the secure reset page at foxora.ai/auth/reset, where you choose a new password. Then return to the app and sign in with it. > **Signed in with Google or GitHub?** If you only ever used Google or GitHub, you don't have a Foxora password to reset — just use the matching Continue with… button to sign in. --- source: https://docs.foxora.ai/accounts/account-and-devices title: Account & devices --- # Account & devices Where your profile, plan, and authorized devices live — and which of them you manage inside the app versus on the web dashboard. ## In the app Open Settings (⌘, / Ctrl+,) → Account to see your name, email, and current plan badge. From here you can: - Open the web dashboard to manage account & billing. - Sign out of this device. ## On the web dashboard Editing your profile, payment method, and plan happens on the hosted dashboard. The desktop app links you straight there. - Profile — name, email, avatar. - Billing — plan, usage, payment method, invoices. - Devices — machines and CLIs authorized against your account. ### Devices and sessions Each machine you sign in on — and each CLI you authorize — becomes an authorized device. Your access token is mirrored to that device’s local runtime so agents can reach the gateway on your behalf, and is refreshed automatically before it expires. > **Token hygiene** Signing out on a device clears its local session and the mirrored runtime token. If you lose a machine, revoke its device from the dashboard. --- source: https://docs.foxora.ai/onboarding/first-run title: The first-run walkthrough --- # The first-run walkthrough The first time you sign in, Foxora runs a short walkthrough that tailors your agents to how you work. It takes about a minute, and every step can be changed later from Settings or the composer. ## The walkthrough, step by step Foxora shows the steps below in order. Some are skipped automatically when they don't apply — the System Check only appears for developer, product, or data-leaning answers, and the Voice step only appears when voice is available on your plan. 1. **Your role** — Pick the option that best describes your work — Developer, Founder, Product / PM, Designer, Marketer, Data / Analyst, Writer, or Something else. This seeds which agents, recipes, and starter prompts Foxora suggests. 2. **Your goals** — Choose one or more things you want to do with Foxora: build & ship software, automate repetitive work, research & summarize, analyze data, create content & design, run ops, browse & do web tasks, or learn & explore. 3. **Autonomy** — Decide how hands-on agents should be by default: - **Ask first** — approve each file edit and command before it runs. - **Auto-approve edits** — edits apply automatically; risky commands still ask. - **Autopilot** — agents act end-to-end without stopping to ask. This sets the default for new sessions and can be changed any time from the composer. See Choosing an autonomy default. 4. **Voice (optional)** — If voice is available, set up a voice agent: a name, a voice, what it should call you, and a personality (Friendly, Professional, Playful, or Concise). You can skip this and configure it later in Settings → Voice. 5. **System check (optional, for builders)** — Foxora checks for the dev tools your agents need (Node, Git, Bun, and friends) and offers a one-click install for anything missing or out of date. Covered in detail in System check. 6. **Connect your browser (optional)** — Foxora can drive your real Chrome through the Foxora Connect extension — research, fill forms, and test your app while you watch it live in the Stage. Click Add to Chrome, or skip for now. The step detects the connection automatically once the extension is installed. 7. **Where to start** — Choose a starting point: Open a folder already on your machine, Clone a repo, or jump straight into a Scratchpad with no setup. Foxora only ever touches folders you open. 8. **A 20-second tour** — A final three-card tour: Just ask (the composer picks the right agent and tools), Agents & crews (build specialists or run a crew), and It remembers (your memory den keeps context across sessions). Click Start using Foxora to finish. > **Saved twice** Your answers are saved locally so they survive a restart, and synced to your account so they follow you to other devices. --- source: https://docs.foxora.ai/onboarding/autonomy title: Choosing an autonomy default --- # Choosing an autonomy default Autonomy controls how much an agent does before asking you. You set a machine-wide default during onboarding, and you can override it per session from the composer. ## The three defaults - Ask first — the safest mode. The agent pauses for your approval before every file edit and shell command. - Auto-approve edits — edits to files apply on their own, but the agent still asks before running anything risky. - Autopilot — the agent works end-to-end and only stops when it needs a real decision from you. ## Overriding per session The default applies to new sessions. Inside any session, the autonomy pill on the left of the composer lets you switch modes — Ask permissions, Accept edits, Auto, or Bypass — for that conversation only. See Autonomy modes. > **Start cautious** New to agents? Start on Ask first until you trust a workflow, then raise autonomy where it saves you time. --- source: https://docs.foxora.ai/onboarding/system-check title: System check --- # System check If you build software, Foxora checks that the tools your agents reach for are installed and current — and installs the missing ones for you, one click at a time. ## What it checks Foxora probes your machine for common developer tools — like Node, Git, and Bun — and shows each one's status: - **Installed** — green check, with the detected version. - **Update available** — yellow, with the minimum version it wants. - **Not installed** — grey, with an install button. ## Installing what's missing 1. **Pick a package manager** — Choose the fallback package manager Foxora should use — Bun (recommended), npm, yarn, or pnpm. Projects with their own lockfile keep using it; this is just the default. 2. **Install or update** — Click Install or Update next to any tool. A spinner shows progress, and if a command fails, the failing command is shown so you can run it yourself. > **Run it again later** You can skip the check during onboarding and revisit your toolchain any time. A clean toolchain means agents can build, test, and run without hitting a missing-binary wall mid-task. --- source: https://docs.foxora.ai/onboarding/reset title: Re-running onboarding --- # Re-running onboarding Your role, goals, and autonomy default aren't locked in — here's how to change them, and how to replay the whole walkthrough. ## Changing answers individually You rarely need to replay onboarding — most answers have a home in the app: - Autonomy — change per session from the composer pill. - Voice — Settings → Voice. - Toolchain — re-run the system check from Settings. - Connections & browser — Settings → Connections. ## Replaying the walkthrough Onboarding completion is tracked both locally and on your account. Clearing the local record makes the walkthrough appear again on next launch. If you want a clean slate — for testing or a fresh persona — reset local preferences from Settings → Advanced. > **Reset is local** Resetting preferences clears local choices like theme and onboarding state. It does not touch your account, your sessions on the server, or your billing. --- source: https://docs.foxora.ai/workspace/layout title: Layout --- # Layout Foxora Desktop is one window split into a handful of regions: a sidebar on the left, the main deck in the middle, the Stage on the right, an optional dock along the bottom, and a title bar across the top. Everything you do lives in one of them. ![Layout — screenshot placeholder](placeholder) ## The regions The shell holds only layout state — every region is a slot the app fills, so the frame is identical no matter what surface is on screen. - Sidebar — the left rail, with sections for Sessions, Files, and Agents. A search button at the top opens the command center. Collapse it, or hover the left edge to peek it back. - Main deck — the center column: your conversation, open files, and surface tabs. This is where most work happens. - The Stage — the right panel. Agents drive it: a live browser, a rendered document, a diff, a table. It opens to about half the window so it’s useful the moment it appears. See the Stage. - Bottom dock — an optional region under the deck for Problems / Find, resizable from its top edge. - Title bar — the host / project breadcrumb, the source-control chip, the search button, and the panel toggles. ## macOS vs Windows / Linux The shell lays itself out differently depending on who draws the window chrome: - macOS & web — floating cards on a canvas. The traffic-light controls sit in the sidebar’s top row, and the main surface carries its own rounded header. - Windows & Linux — one flush, full-width title bar (navigation + breadcrumb + minimize / maximize / close) over flush sidebar, main, and Stage panels. > **Same app, native feel** Foxora detects your OS and renders the matching chrome automatically — floating cards on a Mac, an edge-to-edge title bar on Windows and Linux. The regions and their behavior are identical; only the framing differs. ## Your layout sticks Panel widths, which sections are collapsed, the open project, and the active session all persist locally — reopen Foxora and the window is exactly as you left it. Details in Panels & view state. --- source: https://docs.foxora.ai/workspace/command-center title: Command center --- # Command center Press ⌘K (Ctrl+K on Windows and Linux) to open the command center — one box to navigate the app, run commands, jump to a file or session or agent, and search across your project. ## Open it Hit ⌘K / Ctrl+K from anywhere, or click the search button at the top of the sidebar. Start typing to filter; press Esc to dismiss. ## What it can do Results are grouped by type and ranked as you type. An empty box shows a recents-first resting state; a query fuzzy-matches across every source at once. - Navigate — jump to Sessions, Files, or Agents, or open a recent project. - Run commands — New Session, Open Folder, Settings, open a terminal, toggle the theme, sign out. - Search files — type a name to match files across the open project. Matches are found by the workspace daemon (ripgrep at its core). - Search content — matching lines inside files show up too, so you can jump straight to a line. - Find sessions & agents — recall a past conversation by title, or open / edit any of your agents, crews, and skills. > **It searches as you type** File and content search run against the project daemon, debounced so the palette stays snappy. The newest result always wins, so out-of-order responses never flicker stale matches. ## Moving around - ↑ / ↓ — move through results. - ↵ — run the highlighted item. - Esc — close the palette. Want the rest of the keyboard map? See Keyboard shortcuts. --- source: https://docs.foxora.ai/workspace/keyboard-shortcuts title: Keyboard shortcuts --- # Keyboard shortcuts Foxora defines every shortcut once and labels it for your OS — ⌘ on macOS, Ctrl on Windows and Linux. The full, grouped list lives in Settings → Keyboard. ## How shortcuts work There’s one source of truth for commands and their accelerators. The same binding drives three things: the global keyboard handler, the native OS menus, and the command center. A command only fires when a surface that can service it is on screen — editor actions no-op with no file open, for instance. > **⌘ on Mac, Ctrl elsewhere** Bindings use a portable modifier we write as Mod: it renders as ⌘ on macOS and Ctrl on Windows and Linux. The shortcuts below show the macOS keys; substitute Ctrl for ⌘ on other systems. ## General & navigation - Command Palette — ⌘K - Settings — ⌘, - New Session — ⌘N - Open Folder — ⌘O - Go to File — ⌘P - Go to Symbol — ⌘⇧O - Find in Project — ⌘⇧F ## Panels - Toggle Sidebar — ⌘B - Toggle Right Panel (the Stage) — ⌘J - Toggle Problems (the bottom dock) — ⌘⇧M ## Editor - New File — ⌘T - Close Tab — ⌘W - Reopen Closed Tab — ⌘⇧T - Save — ⌘S - Find — ⌘F - Format Document — ⇧⌥F - Toggle Word Wrap — ⌥Z - Undo / Redo — ⌘Z / ⌘⇧Z ## AI & chat - Inline AI Edit — ⌘I - Fix with Agent — ⌘⇧I - Send message — ↵ in the composer - New line — ⇧↵ - Slash commands — type / in the composer ## See them all Open Settings (⌘, / Ctrl+,) → Keyboard for the complete reference, grouped by category and labeled for your operating system. > **Don't memorize — search** You don’t need this list in your head. Press ⌘K and type the action you want — the command center shows the accelerator right next to it. --- source: https://docs.foxora.ai/workspace/appearance title: Appearance & themes --- # Appearance & themes Make Foxora yours: pick light or dark, a neutral tonal scheme, an accent color, and a UI font. Every change applies live across the whole app and is remembered on this device. ## Where the controls live The same appearance controls show up in two places: the user menu popover, and Settings → Appearance. Both drive one shared theme, so a change in either is instantly reflected everywhere. ## Theme: light or dark Switch between Dark and Light. On first run Foxora follows your system preference, then remembers your choice from then on. ## Scheme: the neutral tone The scheme sets the neutral palette the whole UI is built on — the grays, backgrounds, and surfaces. Pick from a row of tonal swatches: Taupe (the default), Slate, Gray, Zinc, Neutral, Stone, Mauve, Mist, and Olive. ## Accent The accent tints buttons, highlights, and focus states. Choose Neutral, Coral, Amber, Green, Blue, or Violet. ## Font Pick the interface typeface: Inter (default), Geist, DM Sans, or Hanken. > **Local to this device** Your theme, scheme, accent, and font are stored locally on this machine — they don’t follow you to another device. A different computer starts from your system preference again. ## Resetting To start fresh, reset local preferences from Settings → Advanced. That clears device-local choices like theme and onboarding state — it never touches your account, sessions, or billing. See Re-running onboarding. --- source: https://docs.foxora.ai/workspace/panels title: Panels & view state --- # Panels & view state Resize, collapse, and peek the side panels; show or hide the Stage and the bottom dock — and trust that your layout comes back exactly as you left it after a reload. ## Resizing panels Drag the edge between the sidebar and the deck, or between the deck and the Stage, to resize. Widths are clamped to sensible bounds — the sidebar to a comfortable column, and the Stage up to about 60% of the window. Drag the top edge of the bottom dock to make it taller or shorter. ## Collapsing & peeking the sidebar Collapse the sidebar with Toggle Sidebar (⌘B / Ctrl+B) or its header control to give the deck more room. While it’s collapsed, hover the left edge of the window to peek it back into view; click a section to dock it open again, or move away to let it slide shut. > **It collapses itself when it needs to** On a narrow window the sidebar auto-collapses into the hover-peek menu, and it tucks away on its own when you drag the Stage past half the screen. Toggling it by hand always wins — your intent is remembered. ## The Stage and the bottom dock Toggle the Stage (right panel) with ⌘J / Ctrl+J, or the panel button in the title bar. When it opens, it springs to about half the window so it’s immediately useful; a wider saved width is respected. Toggle the bottom dock (Problems / Find) with ⌘⇧M / Ctrl+Shift+M. ## How layout persists Foxora keeps a single local snapshot of your view state under the key foxora.viewstate. It’s read synchronously at startup, so your first paint already has the right geometry — no flash of a default layout. Saved view state includes: - Panel widths, and whether the sidebar and Stage are open. - The active sidebar section (Sessions / Files / Agents). - The last open project and the session to restore. - Open file tabs per project, and your half-typed composer drafts. ```json // localStorage → foxora.viewstate (shape, abbreviated) { "v": 1, "layout": { "sidebarCollapsed": false, "rightOpen": true, "sidebarWidth": 256, "rightWidth": 330 }, "nav": "sessions", "lastProject": "/Users/you/code/app", "lastSessionId": "ses_…" } ``` > **Pointers, not payloads** Foxora persists pointers — file paths and session ids — never their contents. The conversation and your files rehydrate from the engine and disk on reopen, so the snapshot stays tiny and always current. > **Device-local widths** Panel widths are intentionally local to each machine — a 13″ laptop and a 32″ display want different proportions — so they aren’t synced across devices. --- source: https://docs.foxora.ai/sessions/overview title: Sessions overview --- # Sessions overview A session is one thread of work — an agent, its transcript, the folders it can touch, and the mode and crew you're running. Sessions are Foxora's top-level unit: you switch between them like browser tabs, and each one keeps its own context. ![Sessions overview — screenshot placeholder](placeholder) ## What a session holds Open Foxora and you’re always inside a session. Think of it as a single conversation that carries everything that conversation needs: - An agent — the lead doing the work, plus any crew it delegates to. - A transcript — the full back-and-forth, every tool call, and the checkpoints taken along the way. - Projects — the folders you’ve attached, with one marked active as the working directory. - A mode — the autonomy level for this thread (Ask, Auto, Bypass, or Plan). - A crew & tier — the Fast, Premium, or Max line-up the composer is running. ## Sessions, projects, and agents These three are easy to conflate, so it’s worth pinning down how they relate: - A session is the thread. It’s the thing you start, name, switch to, and archive. - A project is a folder you’ve opened. A session can have several projects attached; one is the active working directory. The editor always follows the active session’s active project. See Projects & workspaces. - An agent is the worker. Switching the lead agent gives you a fresh session, so its memory and transcript never bleed into another agent’s. See Multi-agent sessions. > **One thread, one focus** Keep a session to one task. When a request turns into something different, start a new session — it keeps each transcript clean and each memory den on-topic. --- source: https://docs.foxora.ai/sessions/managing title: Managing sessions --- # Managing sessions Create, switch, rename, archive, search, and group your sessions — all from the Sessions sidebar. The list organizes itself by attention and recency so the thread that needs you is always on top. ## Create and switch 1. **Start a session** — Click New session at the top of the sidebar (or press the new session command from the Command Center). You land in an empty conversation, ready for your first prompt. 2. **Switch between sessions** — Click any row to bring that conversation forward. Switching is instant — the engine replays the session's history, and the editor follows it to the session's active project. Foxora remembers your last-open session and returns you to it on the next launch. ## Name a session New sessions get a title derived from your first prompt — the first line, trimmed and sentence-cased. To set your own: - Rename — right-click a row (or open its ⋮ menu) and choose Rename, or press `R`. The title becomes an inline field. A name you set sticks; it won't revert when the next prompt arrives. - Regenerate name — let Foxora propose a fresh title from the conversation so far. ## Session status Each row shows a small indicator that means "needs my attention." The states map to the live run: - Working — the agent is actively running. - Waiting — it's paused on a question or an approval from you. - Done / Error — shown only while unseen — the run finished or failed while you were elsewhere. Open the session and the marker clears. - Idle — a settled session; the row stays clean. > **Ongoing floats to the top** Any session that's working or waiting on you floats to the top of every group, so the thread you're in the middle of is always the first thing you see. ## Search Once you have enough sessions, a search field appears above the list (focus it with `⌘F` / `Ctrl+F`). It matches case-insensitively across each session's title and its attached project names and paths — so typing a project name finds every session that touches it, no extra filter needed. ## Group and sort The view options menu (the sliders icon) controls how the list is laid out. Group by: - Recency — automatic Needs attention, Today, Yesterday, This week, and Older buckets. - Custom groups — your own named buckets. Drag a session onto a group to file it; create one from New group…. Everything ungrouped falls back to the recency buckets. - Project — grouped by each session's active project. - Flat list — no headers, just rows. Within a group, sort by Recently updated or Name, and use Show → Needs attention to hide everything that isn't waiting on you. > **Grouping is local** Your custom groups and view preferences are saved on this device. The sessions themselves live on the engine and follow you everywhere; the way you choose to arrange them is yours alone. ## Archive and delete Done with a session but want to keep it? Archive it from the row menu. Archived sessions drop into a collapsed section at the bottom of the list — out of your inbox, still searchable, and unarchivable any time. To remove one for good, choose Delete (`D`); a confirmation reminds you it permanently removes the session and its history. --- source: https://docs.foxora.ai/sessions/projects title: Projects & workspaces --- # Projects & workspaces A project is a folder you've opened. Attach one to a session and it becomes the working directory agents read and write in. Foxora only ever touches the folders you open — nothing else on your machine is in reach. ## Three ways to start a workspace During onboarding — and any time after, from the Command Center — you choose where a session works: - **Open a folder** — Point Foxora at a folder already on your machine. It attaches to the active session as a project and becomes the working directory. The editor opens on it immediately. - **Clone a repo** — Give Foxora a Git URL and it clones the repository into a fresh folder, then opens it as the session's project — ready to build, test, and commit. - **Scratchpad** — No setup, no folder. The scratchpad drops you straight into a conversation for quick questions, planning, or anything that doesn't need files on disk. You can open a folder later without losing the thread. ## The active working directory A session can have more than one project attached, but exactly one is active — that's the working directory agents operate in, and the folder the editor shows. The link runs both ways: switching sessions opens that session's active project, and opening a brand-new folder attaches it to the session you're in. > **Working dir vs. path** A session's working directory is its view of a project. When a session runs in an isolated worktree, the working directory is that worktree; otherwise it's the shared folder path. The editor follows whichever is in effect. ## Foxora only touches what you open This is a hard boundary, not a convention. Agents read and write inside the folders attached to a session and nowhere else — the rest of your machine is out of reach. Opening a folder is how you grant access; closing or detaching it takes the access away. > **Group sessions by project** Working across a few repos? Switch the sidebar to group by project to see every session, bucketed under the folder it touches. --- source: https://docs.foxora.ai/sessions/forking title: Forking & checkpoints --- # Forking & checkpoints Every message has a hover toolbar: copy it, edit & resend it, fork a new session from it, or restore the workspace checkpoint taken for that turn. Together they let you explore a different path without losing the one you're on. ## The message toolbar Hover any message — yours or the agent's — and a small toolbar appears beneath it. Which buttons show depends on the message: - Copy — copies the message text. Always available. - Edit & resend — on your prompts: tweak the wording and run it again from that point. - Retry — on an agent response: re-run the turn. - Fork from here — branch a new session that starts from this message. - Restore checkpoint — roll your files back to the snapshot taken for this turn. ## Forking a conversation Fork from here spins up a new session that branches at the message you picked. The original session is untouched — you keep its transcript exactly as it was — while the fork lets you try a different prompt, a different approach, or a different agent from that point forward. > **Compare two paths** Forked sessions are ordinary sessions, so you can run the original and the fork side by side on the Stage and compare where each one lands. ## Restoring a checkpoint Foxora captures a workspace checkpoint at each turn — a snapshot of your files before the agent changed them. When one exists, the message shows a checkpoint chip. Restore checkpoint rolls your working tree back to that snapshot, so a turn that went sideways is one click to undo. > **Restore touches your files** Restoring a checkpoint reverts files on disk to the snapshot for that turn. It rewinds the workspace, not the conversation — the transcript stays intact so you can see what happened. ### Buttons appear when they apply A button only renders when its action is available: edit & resend on your own prompts, retry on responses, and restore only when a checkpoint exists for that turn. If a row shows fewer buttons, the missing actions simply don't apply there. --- source: https://docs.foxora.ai/sessions/multi-agent title: Multi-agent sessions --- # Multi-agent sessions In Foxora, each agent gets its own session — multi-agent means multi-session. Switch the lead and you switch threads; run several at once and watch one of them live on the Stage, right next to the conversation you're driving. ## One agent, one session Switching the lead agent doesn’t reuse the current thread — it opens that agent’s own session. Each agent keeps a separate transcript and memory den, so nothing leaks between them: your research agent never sees your refactor agent’s scratch work, and vice versa. > **Why a fresh thread?** Bleeding two agents’ context into one transcript muddies both. Giving each its own session keeps memory clean and makes each one’s history easy to follow. ## Running several at once Because sessions are independent, you can have several running in parallel. A session that’s working keeps going while you switch to another; the sidebar floats anything working or waiting on you to the top, and surfaces a marker when a background run finishes or needs you. See session status. ## A second session on the Stage To watch two conversations at the same time, open one on the Stage. From a session’s row menu choose Open in Stage — that session mounts as a live conversation on the right, with its own stream, history, and composer, while you keep driving the main one on the left. > **Delegate, then watch** Hand a long task to one agent, open its session on the Stage, and keep working in the main conversation. You see its progress without losing your own place. To learn how a lead delegates to a crew under the hood, see Agents & crews. ### When the Stage view isn't available Mounting a second session on the Stage needs a build that injects the conversation renderer. Where that isn’t available, the Stage shows a short notice instead of the embedded session — everything else about the session keeps working. --- source: https://docs.foxora.ai/composer/overview title: Your first message --- # Your first message The composer is the one box you type into. You don't pick a tool or a mode first — you just describe what you want, and Foxora picks the right agent, skills, and tools to do it. ![Your first message — screenshot placeholder](placeholder) ## Anatomy of the composer The composer is an auto-growing text box with a small toolbar underneath. Left to right, the toolbar holds: - Autonomy pill — how much an agent does before asking you (Ask, Accept edits, Auto, Bypass). - Attach (+) — add files, photos, a folder, or open the slash-command list. - Mic — speak instead of type, with a caret for device + voice settings. - Context meter — a ring showing how full the conversation's context window is. - Crew & tier chip — which crew and tier (Auto / Pro / Max) runs the turn. ## Sending your first message 1. **Just describe what you want** — Type a request in plain language — "build me a landing page for a coffee shop" or "why is this test failing?" You don't need to name a tool; the agent figures out the steps. 2. **Send it** — Press Enter to send, or click the send button. Shift+Enter inserts a newline. A message with only an attachment (say, a screenshot) is sendable with no text at all. 3. **Watch it work — or stop it** — The reply streams into the transcript above. While a turn is running, the send button becomes a Stop square — click it any time to interrupt. If you type while it's busy, your next message queues behind the active turn. > **Type / for shortcuts** Start a line with `/` to open the slash-command palette — a quick way to phrase common tasks like `/build` or `/research`. --- source: https://docs.foxora.ai/composer/slash-commands title: Slash commands --- # Slash commands Type `/` at the start of a line to open the command palette. A slash command is just a faster way to phrase a turn — there's no separate command engine; the same agent carries it out with its skills and tools. ## Using the palette Type `/` and the palette floats above the input. Keep typing to filter, use ↑/↓ to move, and Enter or Tab to choose. Commands that take an argument insert the trigger and leave the cursor ready for you to type the rest, then send with Enter. Commands that need no argument run the instant you pick them. ```bash /research the best vector DBs for RAG ``` ## Prompt commands vs client commands There are two kinds of command: - Prompt commands expand a template into the message sent to the agent. Anything you type after the trigger fills the $ARGUMENTS slot. `/research the best vector DBs` becomes a full "research this across the web…" instruction. - Client commands run an app action and send nothing to the agent — like switching the model or starting a new session. ## The built-in commands ### Prompt commands - `/build` — build an app, page, or feature end to end. - `/fix` — reproduce, root-cause, and fix a bug, then verify. - `/research` — research a topic across the web and cite sources. - `/explain` — explain a file, symbol, concept, or question. - `/test` — write and run tests, then report results. - `/plan` — draft a step-by-step plan with no code yet. - `/deploy` — detect the framework, build, and ship to hosting. - `/commit` — stage, commit with a clear message, and open a PR. - `/review` — review the current changes for bugs and cleanups. - `/refactor` — restructure code without changing behavior. - `/optimize` — find and fix a performance problem. - `/document` — write docs for code or a feature. - `/screenshot` — capture the screen and describe it (runs on select). - `/help` — list what Foxora can do (runs on select). ### Client commands - `/model` — open the crew & tier picker. - `/new` — start a new session. - `/clear` — start fresh with an empty context (your prior session stays in the sidebar). > **Bring your own commands** Project-authored commands (e.g. `.foxora/commands/*.md`) fold in alongside the built-ins, so a repo can ship its own shortcuts without touching the composer. --- source: https://docs.foxora.ai/composer/attachments title: Attachments --- # Attachments Give the agent something to work from — drop in files, images, or a whole folder. Attachments stage as tiles above the input and ride along with your next message. ## Three ways to attach - Drag & drop — drag files from Finder or Explorer, or paths from the in-app file explorer, onto the composer. A “Drop to attach” overlay confirms the target. - Paste — paste an image straight from your clipboard (a screenshot, say) and it stages as an image tile. - The + button — open the attach menu for Add files or photos or Add folder, which open a native picker. ## Staged tiles Each attachment shows as a chip above the input, with a glyph for its kind (image, file, audio, video, code, or folder), its name and size, and an upload progress bar while it’s reading in. Remove one by clicking the × on its tile. An attachment-only message — no text — is perfectly valid. ## Folders Adding a folder stages the folder reference, not a recursive dump of every file. The agent reaches into it with its file tools as the task needs — so a large directory doesn’t balloon your context up front. > **Open a project for ongoing work** Attachments are great for a one-off. For sustained work on a codebase, open a project instead so the agent has the whole working tree. See the context meter to keep an eye on window usage. --- source: https://docs.foxora.ai/composer/autonomy-modes title: Autonomy modes --- # Autonomy modes The pill on the left of the composer sets how much an agent does before it stops to ask you — for this session only. It starts from your onboarding default and you can change it any time. ## The modes - Ask permissions (1) — the safest mode. The agent pauses for your approval before every file edit and command. - Accept edits (2) — file edits apply on their own; the agent still asks before running anything risky. - Auto mode (3) — the agent works end-to-end and only stops when it needs a real decision from you. - Bypass permissions (4) — nothing is gated. The pill turns amber as a reminder that approvals are off. ## Per session, not global The pill changes the mode for the current conversation and is remembered on that session. New sessions start from the machine-wide default you picked during onboarding — see Choosing an autonomy default. > **Where's Plan mode?** Planning isn’t an autonomy tier — it’s the /plan slash command, which asks the agent to outline the work before writing any code. Reach for it when you want to review the approach first, regardless of your autonomy setting. > **Start cautious** New to a workflow? Stay on Ask permissions until you trust it, then raise autonomy where it saves you time. --- source: https://docs.foxora.ai/composer/crew-picker title: Picking a crew & tier --- # Picking a crew & tier The chip on the right of the composer picks a crew and tier — not a raw model. The tier sets the horsepower; the crew sets who works the turn and how they're orchestrated. ## Tiers: Auto, Pro, Max Every crew runs at a tier, and the tier is what drives cost and capability: - Auto — the fast tier. Quick and inexpensive, the default for most turns. - Pro — the premium tier. More capable for harder, multi-step work. - Max — the top tier. The most capable, for the heaviest tasks. Which tiers you can pick depends on your plan. The tier maps to a gateway pool; each agent's role then resolves to a concrete model at that tier — so you never hardcode a model, you pick a level. ## Picking a crew 1. **Open the picker** — Click the crew chip (or run `/model`). The picker lists the built-in Auto / Pro / Max crews plus any crews you've built. 2. **Read the stats** — Each crew shows a quick stat line so you know what you're activating: - agents — the lead plus its members. - skills — distinct skills across the crew. - tools — distinct tools the crew can reach. - models — the distinct models the roles resolve to at this tier. 3. **Select it** — The chosen crew is remembered on the session. The turn then runs with that crew's tier model plus its orchestration stance and member delegation. > **Crew, not just a model** Picking a crew is more than picking a model: it activates the orchestrator overlay and the member line-up. A larger crew can split work across specialists, which you'll see as a swarm in the transcript. --- source: https://docs.foxora.ai/composer/voice title: Voice chat --- # Voice chat When voice is available, the mic in the composer lets you talk to Foxora instead of typing — and have replies spoken back. There are two ways to capture: push-to-talk and a hands-free call. ## Two capture modes - Push-to-talk — press and hold the mic to record; release to transcribe and send. Letting the pointer slip off while held cancels without sending. A one-shot dictation. - Hands-free call — click the mic to start a continuous listen → send → speak loop. Foxora listens, sends each utterance, speaks the reply, and listens again — a live conversation. Toggle Hold to record from the mic’s caret menu to switch between them, and pick your input device there too. While capturing, the input becomes a live waveform that reads Listening…, then Transcribing…. ## Spoken replies & wake phrase With spoken replies on, Foxora reads back the answer for voice turns only — typed turns stay silent so the room doesn’t suddenly start talking. If you begin speaking again, any in-progress spoken reply is cut off so you’re never talking over it. You can also set an optional wake phrase (like “Hey Foxora”) in Settings → Voice. > **Gated on availability** Voice appears only when it’s available on your plan. If you don’t see the mic, voice isn’t enabled for your account — everything else in the composer works exactly the same by typing. --- source: https://docs.foxora.ai/composer/context title: Context & compaction --- # Context & compaction The ring meter next to the crew chip shows how full the conversation's context window is. Click it for an honest breakdown, and compact the session to reclaim room without losing the thread. ## The context meter The ring fills as the conversation grows and shows the percentage used. It stays neutral, turns amber as you approach the limit, and red when it’s nearly full. Click it to open the breakdown. ## What the breakdown shows The popover separates what actually sits in the window from the gross totals, so the number reads honestly: - Window fill — a stacked bar of cached (re-sent context, billed at a fraction) vs fresh input, against the free space left. - This turn — input split into cached vs fresh, and output split into reasoning vs answer, shown only when the provider reports those fields. - Session total — the same breakdown summed across every turn, with the turn count. > **Cached isn't the cost** Cached input is context re-sent each turn and billed at a fraction of fresh input — so the gross token total isn’t your bill. The meter breaks it out so you can read it correctly. ## Compacting a session As the window fills, Foxora compacts older turns out of the live context to keep it bounded — the breakdown notes how many turns are compacted (they’re still recallable, just no longer in the live window). You can also compact on demand: the Compact session button in the popover summarizes older turns out of the window in place. Start a fresh session is the secondary escape hatch when you’d rather begin clean. > **Estimated vs exact** When the gateway reports real usage, the numbers are exact. If a provider gives none, the meter falls back to an estimate from message size and labels it as approximate. --- source: https://docs.foxora.ai/composer/transcript title: Reading the transcript --- # Reading the transcript The transcript above the composer is where a turn plays out — the reply, the tools the agent ran, its reasoning, the artifacts it produced, and any sub-agents it delegated to. ## Turns and phases Each exchange is a turn: your message, then the agent’s work. A live turn animates through named phases — processing, thinking, working, responding — and a turn can re-enter thinking or working between steps as it chains. ## Tool cards, reasoning, and artifacts - Tool cards — each tool call (read a file, run a command, search the web) renders as a card you can expand to see inputs and results. - Reasoning — the model’s thinking appears as a distinct reasoning block, separate from its answer prose. - Artifacts — generated files, diagrams, tables, and the like stream in as artifact cards, often mirrored on the Stage. ## Swarm: when a crew delegates When the lead hands work to its members, the transcript shows a swarm — each sub-agent’s tools nest under it, running under the session’s autonomy mode. It’s how a crew reads on screen: several specialists working in parallel under one turn. ## Agentic vs verbose view The transcript has two views. Agentic (the default) is a condensed narrative — the gist of what happened, tools folded down. Verbose shows the full reasoning and every tool call. Switch when you want to follow exactly what the agent did, then switch back to keep the feed readable. > **A tool needing approval always shows** Even in the condensed agentic view, a tool call waiting on your approval shows its full card — it’s interactive, so it can’t be hidden. See Approving actions. --- source: https://docs.foxora.ai/composer/approvals title: Approving actions --- # Approving actions When an agent needs your go-ahead — to run a command, apply an edit, or answer a question — it pauses and asks right in the transcript. Nothing risky happens behind your back. ## Approving or declining a tool call Under Ask permissions (and for risky actions under Accept edits), a tool call that needs sign-off shows an approval bar beneath its card — never hidden behind a chevron. Review what it’s about to do, then Approve to let it run or Decline to skip it. The turn continues either way. ## Answering an ask_user question Sometimes the agent doesn’t need permission — it needs an answer. An ask_user question renders as its own interactive block in the transcript: type your reply (or pick an option) and the turn picks up with your input, no command line required. ## Autonomy sets the bar How often you’re asked depends on the autonomy mode. Ask permissions gates everything; Accept edits gates only risky commands; Auto and Bypass let the agent proceed without stopping. Sub-agents in a swarm auto-approve under the session’s mode rather than asking separately. > **Bypass means no gate** In Bypass permissions there are no approval bars at all — the agent runs everything. Use it only when you trust the workflow end to end. --- source: https://docs.foxora.ai/stage/overview title: The Stage --- # The Stage The Stage is the right-hand panel the agent works on. It's one surface that morphs — a terminal while a command runs, a browser while the agent researches, an editor when it opens a file, a plan while it works through steps. You watch the work happen, and switch between everything that's open from a single menu. ![The Stage — screenshot placeholder](placeholder) ## One surface, many shapes Rather than a wall of tabs, the Stage shows one surface at a time — the one most relevant to what the agent is doing right now. As work moves, the Stage moves with it: it opens a terminal to run a build, flips to a browser to check the result, opens the file it just edited. Every surface the agent (or you) opens stays available behind the switcher. ## The now-strip & switcher The bar at the top of the Stage — the now-strip — is a single control. It shows an icon chip (whose tint carries status), the active surface’s title, and a count. Click it to open the switcher: a dropdown with two zones. - **On the Stage** — everything currently open. Click a row to switch to it; hover to close it. With enough open, rows group by category. - **Open new** — start something on demand: a Terminal, Browser, Source Control, and more, supplied by the app. A back arrow steps you to the previously-focused surface, so flipping between two views is one click. The count pill glows when the agent has parked new surfaces you haven’t looked at yet; opening the switcher clears the glow. ## Live status Each surface carries a status that the chip and switcher reflect: idle, live (the agent is actively working it, shown as an accent ring or pulsing dot), done, or error (a danger tint). You can tell at a glance whether the terminal is still running or the browse has finished. ## Preview, code, copy, download Surfaces that have both a rendered form and a source — a Markdown file, a mermaid diagram, an HTML or SVG artifact, a CSV — get a Preview / Code toggle in the header, so you can flip between the rendered result and the raw text. Every content-bearing surface also gets a Copy and a Download action: a file copies its path and saves to a folder, a diagram copies its source and downloads with the right extension, a preview copies its URL. > **It's driven by events** The Stage is built from a stream of surface events — open, update, focus, close. The same model renders whether the agent is working live or you’re revisiting a finished session, so nothing on the Stage is ever a dead screenshot. --- source: https://docs.foxora.ai/stage/terminal title: Terminal --- # Terminal When the agent runs a command, the Stage opens a terminal and you watch the output stream in — the same shell you can type into yourself. ## A real terminal The terminal surface hosts a full interactive shell. The agent’s commands run there and you see every line as it happens; you can also click in and run commands yourself in the same working directory. The header shows the current directory and the command being run. ## Streamed output & exit codes Output is colour-coded by stream — standard output in neutral, errors in red, and the commands themselves prefixed with $. The view sticks to the bottom as new lines arrive, and a finished command shows its exit code: green for success, red for a non-zero exit. > **Always the right machine** Commands run where your project lives. Whether the agent runs in the cloud or locally, terminal work is relayed to your device so paths, tools, and environment are exactly what you’d get in your own shell. See autonomy modes for how command approval works. --- source: https://docs.foxora.ai/stage/browser title: Browser --- # Browser The agent browses the web in your real Chrome — the same browser, signed into the same accounts — and you watch it work live on the Stage. There's also a built-in preview for local dev servers. ## Your real Chrome, driven by the agent For browsing real sites, Foxora drives your Chrome through the Foxora Connect extension — not a throwaway headless browser. That means the agent works as you: signed into your accounts, with your cookies, your extensions, your sessions. The Stage shows a read-only preview of what’s on screen, badged Your Chrome, so you can follow along without taking over. > **The Stage is never an embedded browser** A real, non-local site is never loaded inside the Stage. The actual browsing happens in your Chrome via the extension; the Stage just mirrors it. If the extension isn’t installed yet, the surface shows an Install Foxora Connect button and an Open in your browser link instead. Set it up from Connections. ## Following along - **The agent navigates** — As the agent moves between pages, the address bar and the preview update to match. The frame shows the latest screenshot of the page it’s working. - **Open it yourself** — Hit Open in your browser to jump to the current page in Chrome and pick up where the agent is — handy when you want to take over a step manually. ## Local dev-server preview A localhost URL — your dev server — can render right on the Stage in a sandboxed preview with an editable address bar. Type a URL and press Enter to navigate, reload from the toolbar, or open it in your browser. Click the instrument control on a local preview to select elements, annotate, and capture the console — turning the preview into a feedback surface you can point the agent at. ### Taking control When the agent drives a streamed browser session, a Take control button lets you grab the wheel — your clicks, scrolls, and keystrokes go straight to the page — then hand it back to the agent when you’re done. --- source: https://docs.foxora.ai/stage/editor title: Files & the editor --- # Files & the editor Files open on the Stage in a real editor — Monaco, the engine behind VS Code — with a dirty-diff gutter, formatting, a diff view, and a one-keystroke 'Fix with Agent'. Images, PDFs, Office docs, and CSVs render with their design, not as flat text. ## Opening a file When the agent reads or edits a file, it opens on the Stage; you can also open one from source control or the Files surface. Code shows with full syntax highlighting, a path breadcrumb across the top, and the editor toolbar on the right. ## The editor toolbar - Format document (⇧⌥F) — tidy the file, with an optional format-on-save toggle. - Word wrap (⌥Z) — wrap long lines on or off. - View changes — appears when the file has uncommitted edits; flips to a HEAD-vs-working diff and back. Lines you’ve changed since the last commit are marked in the dirty-diff gutter down the edge of the editor, so edits — the agent’s or yours — are visible as you scroll. ## Fix with Agent The editor runs real language intelligence — diagnostics, hover, go-to-def, references, rename. When there’s a red squiggle, right-click it (or press ⌘⇧I) and choose ✦ Fix with Agent to hand that diagnostic straight to the agent. Fix All with Agent sends every problem in the file at once. ## Images, PDFs, Office docs & data Not everything is code. The file surface renders each type with its real design: - Images — zoom, pan, and fit. - Audio & video — an inline player. - PDF, Word, PowerPoint — rendered with their layout — pages, slides, formatting — not stripped to plain text. - CSV — a real, scrollable, sortable-looking table with a sticky header (or its raw text in Code mode). - Markdown, mermaid, HTML, SVG — rendered live, with a Preview / Code toggle. > **One toggle for both forms** For any file with a rendered and a source form, the header’s Preview / Code switch flips between them — see the table, then peek at the raw CSV; read the doc, then read its Markdown. --- source: https://docs.foxora.ai/stage/source-control title: Source control --- # Source control A session-aware git panel: the open project's changes, grouped by who made them, with a commit box that commits only this session's work — plus branch isolation and one-click pull requests. ## Your changes, attributed The source-control surface lists the open project’s changed files grouped by owner: - Your changes — the files this session touched. - Other — work in progress from other live sessions on the same project. - Other / untracked — everything else the working tree shows. Each row shows a git status letter and the file’s path; clicking it opens the file in the editor. The header shows the current branch. ## Commit & pull request The commit box commits only this session’s changeset — the same path the agent uses for its own commits — so parallel sessions don’t step on each other. Write a message and Commit, or Create pull request to open one via the GitHub CLI (the panel tells you if the CLI still needs setting up). ## Isolating a session Need a session to work on its own branch? Isolate it to spin up a git worktree; the header tags it isolated. When you’re done, Merge folds the branch back into the base and stops isolating. The panel refreshes itself live while it’s on the Stage. > **Sessions own their changes** Attribution comes from the active session, so source control and the rest of the app stay in sync about who changed what. See Sessions for the bigger picture. --- source: https://docs.foxora.ai/stage/plans-runs title: Plans, runs & crews --- # Plans, runs & crews For multi-step and multi-agent work, the Stage shows the shape of the job — the plan as a live checklist, a single agent's run as a timeline, a workflow as a node sequence, and a crew as a board of agents at work. ## Plan — the live to-do list The plan surface is the agent’s working plan as a checkable list. Each step shows its state — done (check), working (spinner), waiting (blocked), or error — with the active step highlighted and completed steps struck through. The header carries overall progress, a state pill (Running / Done / Failed), and while the run is live, a Stop button that aborts the turn. ## Run — one agent’s timeline The run surface shows a single agent’s execution as a vertical timeline: each step a dot on a connecting rail, with its label and detail, and a work-status dot showing where it is. It’s the trace of what the agent actually did, step by step. ## Flow — a workflow as nodes The flow surface renders an automation as a top-down sequence of nodes — trigger → actions → conditions → output — each a card with an icon, label, and status, joined by a rail. The panel is narrow, so the path runs vertically rather than as a sprawling 2-D graph. ## Crew — the team at work When you run a crew, the crew surface is a live board of every agent: one row each, with an avatar, role, the activity it’s on right now, and a work-status dot. The header counts how many are working. It’s the team-view for multi-agent runs. > **Built for autonomous work** Plans, runs, flows, and crews come into their own when an agent works end-to-end. Learn how to assemble specialists and crews in Agents & crews. --- source: https://docs.foxora.ai/stage/supporting-surfaces title: Supporting surfaces --- # Supporting surfaces Beyond the headline views, the Stage hosts a set of supporting surfaces — a media vault, a session library, recalled memory, the usage meter, schedules, and a file explorer. ## Media — the asset vault The media surface is a gallery of standalone assets: files you shared and one-offs the agent generated — images, audio, video, PDFs, generated docs and data — kept separate from your project files. Tiles show a thumbnail where they can, badge each asset’s origin (shared, or which agent made it), filter by type, and download on hover. Click one to preview it on the Stage. ## Library — everything this session used The library collects everything the session produced or touched — files, attachments, links, and generated artifacts — in one filterable list. Click an item to re-open it: a file opens the editor, a link opens the browser surface. ## Memory — what the Den recalled The memory surface is a read-only view of what the memory den recalled for the current context, grouped by layer — Session, Project, and You — with each memory’s category and when it was learned. It’s how you see why the agent knows what it knows. ## Usage — the session bill The usage surface is the session’s token-and-cost meter: headline totals (cost, tokens in, tokens out), a live context-window fill, and a per-model breakdown. Everything routes through the gateway, so this is the real, attributable cost for the session. ## Schedule — automations The schedule surface lists triggers and scheduled automations for deployed agents — one row per schedule with its cadence, next run, last outcome, and enabled state. ## Files — the explorer The directory surface is a navigable folder listing — a real file explorer on the Stage. It lists a folder live, navigates in place with its own breadcrumb, sorts folders before files, and opens any file as its own Stage surface. > **Resilient by design** The Stage maps each surface kind to a renderer, and a kind with no renderer yet degrades to a friendly placeholder rather than a crash — so new capabilities can appear on the Stage the moment the engine starts emitting them. --- source: https://docs.foxora.ai/stage/visuals title: Inline visuals --- # Inline visuals When the agent's answer is a diagram, a table, or an equation, Foxora draws it instead of dumping the source. Mermaid diagrams, CSV/JSON tables, and LaTeX math all render inline — in chat and on the Stage — with a fall-back to the raw source if anything's off. ## One registry, both places A single set of visual renderers powers both the inline cards in chat and the full-height surfaces on the Stage. A fenced code block or an artifact whose language Foxora recognises gets drawn; anything it doesn’t recognise simply shows as highlighted source. Every renderer is crash-proof by contract — a load failure or malformed source falls back to exactly the code you’d have seen anyway. ## Mermaid diagrams Fenced mermaid blocks compile to an SVG diagram, themed from the live design tokens so it matches light or dark mode — no hardcoded colours. Diagrams render in a strict security mode that strips any scripts from agent-authored source, and a half-streamed diagram shows its source until it’s complete and valid. ## Tables CSV (and table artifacts) render as a real, scrollable table with a sticky header — zoomable like every Stage visual — and you can flip to the raw text with the Preview / Code toggle. ## Math LaTeX / math sources render with KaTeX. Malformed TeX shows an inline error marker rather than crashing, and a hard failure falls back to the raw source. > **See the source any time** On the Stage, the header’s Preview / Code toggle flips a diagram, table, or doc between its rendered form and its source — and Copy / Download grab the source or save the file with the right extension. --- source: https://docs.foxora.ai/agents/overview title: Agents overview --- # Agents overview An agent in Foxora is a worker with an identity, a brain, and a set of capabilities — not just a chat window. The Agents workbench is where you build them, wire their tools and skills, and put them to work. ![Agents overview — screenshot placeholder](placeholder) ## An agent, not a chatbot A chatbot answers a message and stops. An agent does the work — it reads your real files, runs commands, searches the live web, drives a browser, and carries a multi-step task to done, pausing only when it needs a real decision from you. Every Foxora agent stands on the same operating core (the reasoning loop, planning, memory, and stopping rules). What makes one agent different from another is its identity (a persona), its role (which brain it routes to), and its capabilities (tools, skills, and connected apps). ## Anatomy of an agent - Identity — a name, an icon, and a persona (the “soul”: how it describes itself, its personality, values, and voice). - Role — the function it performs, picked from Foxora’s core roles. A role is a routing tag that decides which model the agent runs on. See Roles explained. - Instructions — your own guidance, layered on top of the role’s built-in doctrine. - Capabilities — tools, skills, and connected apps / MCP servers. - Where it runs — surfaces (chat, code, web…) and external channels (Slack, email…). ## The Agents workbench Open Agents from the sidebar. The workbench groups everything an agent is made of into three families: ### Workforce — who does the work - Crews — teams of agents led by an orchestrator. See Crews. - Agents — the agent library: Foxora’s built-ins plus the ones you create. - Templates — pre-wired starting points. See Templates. ### Toolkit — what they’re made of - Skills — reusable how-to playbooks an agent loads on demand. See Skills. - Tools — the read-only catalogue of capabilities (filesystem, shell, web, vision, memory…). New capability comes from connecting apps, not authoring tools. - Memory — the Memory Den, the shared long-term memory your agents draw on. - Connections — apps and MCP servers that become live tools. Opens Settings → Connections. ### Work — what they run - Tasks — work assigned to agents and crews. - Runs — the queue and run history. - Triggers — schedules, events, and webhooks that start an agent unattended. > **Two ways to build** Click + New agent and pick a path: Build with AI (describe it, Foxora drafts it) or Start from scratch (the manual editor). Both land in the same editor. --- source: https://docs.foxora.ai/agents/build-with-ai title: Build with AI --- # Build with AI The fastest way to a new agent: give it a name and say what it's for. Foxora composes the persona, instructions, and the right skills and tools, then drops the result into the editor for you to review. ![Build with AI — screenshot placeholder](placeholder) ## Start the AI Builder 1. **Open the create fork** — In the Agents workbench, go to Agents and click + New agent. You'll see two options: Build with AI and Start from scratch. Pick Build with AI. 2. **Describe the agent** — Give Foxora a short brief: - Name — e.g. Release Manager. - What's this agent's job? — one or two sentences, e.g. "Own releases: cut the version, write the changelog, tag and publish." - Department (optional) — e.g. Engineering. Just gives Foxora context to pick a fitting setup. 3. **Let Foxora draft it** — Click Draft agent. The composing runs server-side on the engine: Foxora writes the persona and instructions, and selects the skills and tools that fit the job — creating new skills when it needs them. You'll get a toast when it's done. If a role wants a specialized model: when the composer thinks a role would do better on a particular model, it surfaces a "Pick a custom model" hint. That's a suggestion — the agent still runs on its managed tier unless you pin one. See Models & tiers. 4. **Review and save** — The draft opens in the same manual editor — nothing is saved yet. Walk the tabs, adjust anything, optionally run a quick test, then click Create agent. > **The AI never leaves you stuck** If the engine can't be reached or the model returns nothing, the modal stays open with the reason and a Build manually escape that opens a blank editor seeded from your brief — never a silent, half-built draft. --- source: https://docs.foxora.ai/agents/build-manually title: Build manually --- # Build manually The manual editor is the full builder. Identity stays visible at the top; the rest is a row of tabs — Persona, Instructions, Model, Tools, Skills, Connections, Test — with a live preview on the right. ## Identity — always on top Above the tabs, three fields stay visible no matter where you are: - Icon — pick from the icon library. - Name — e.g. Release manager. It must be unique. - Role — the function this agent performs. Picking a role gives the agent Foxora’s managed doctrine and a managed brain; your instructions layer on top. See Roles explained. ## Persona The persona is the agent’s “soul” — who it is, not what it can do. Four short fields: - Title — one line, how the agent describes itself, e.g. “a senior software engineer.” - Personality — e.g. “Capable, direct, proactive.” - Values — what it optimizes for, e.g. “Do the work; tell the truth; least surprise.” - Voice — e.g. “Concise and warm; technical when it counts.” At the bottom, Surfaces picks where the agent answers (chat, code, agents, web, cli). ## Instructions This is this agent’s own guidance — how it behaves, beyond its role. The role already provides Foxora’s managed doctrine, so instructions are an addendum, not the whole brain. Leave it empty to run purely on the role. > **Specialize with skills, not forked prompts** Resist pasting a giant prompt here. If the agent needs a repeatable procedure, make it a skill and attach it — skills load on demand and are reusable across agents. ## Model Most agents should stay Foxora-managed: the agent runs on its crew’s tier, and Foxora resolves the best model for that tier automatically, with provider fallback. You never type a raw model name. - Fast — quick, everyday tasks. - Pro — the default; strong general-purpose work. - Max — the hardest reasoning and the trickiest builds. Switch to Your own model to pin a specific model from a provider you’ve connected — that’s bring your own keys. Full details in Models & tiers. ## Tools Pick the tools this agent may use, from the workspace belt (read, write, edit, bash, grep, lsp_inspect…) plus anything added by your connected MCP servers. To grow the catalogue, connect an app under Connections. ## Skills Attach the skills the agent should load. You can spin up a new skill inline with New skill (name + description) without leaving the editor, then flesh out the playbook later in the Skills section. ## Connections Wire the agent to the outside world: - Apps & MCP servers — the connected apps / MCP servers this agent can use. Connect more with Connect app, which opens Settings → Connections. - Channels — external places it runs (Slack, email, Discord…), each needing a connection. ## Save Click Create agent (or Save agent when editing). It appears in the Agents library and is available to the composer and to crews. The Test tab lets you run a real turn before you ship it. > **Built-in agents are read-only** Foxora’s built-in agents (Coder, Researcher, Scout…) show their model, tools, and skills, but their persona and instructions are managed for you — the Persona and Instructions tabs only appear on agents you create. --- source: https://docs.foxora.ai/agents/testing title: Testing an agent --- # Testing an agent The Test tab runs a real turn against the agent you're building — same engine, same persona — so you can see how it answers (and which tools it reaches for) before you ship it. ## Run a test turn Open the Test tab in the agent editor, type a prompt (it starts with a sensible default like “In one sentence, who are you and what do you do?”), and click Save & run. Running first saves the agent — so the turn uses its very latest persona, instructions, and wiring — then sends a one-off message to it. The response streams into the panel below. ## Tools called Above the output, Foxora lists the tools the agent invoked during the turn, in order. It’s the quickest way to confirm the agent is reaching for the right capabilities — and not, say, ignoring a skill you attached. ## Writes and commands stay gated A test run executes in Ask mode: anything that writes a file or runs a command is still gated, so a test can’t quietly change your project. It’s a safe dry run of the agent’s behavior. > **When a test fails** If the run errors, the editor shows a clear failure callout with the reason — an unreachable engine, an empty model response, or a tool error. Fix the cause (often a missing connection or an empty name) and run again. Use Clear to reset the panel. > **Test, then ship** A green test isn’t a guarantee, but it catches the obvious problems early. Once it answers the way you want, save and put it to work — or add it to a crew. --- source: https://docs.foxora.ai/agents/roles title: Roles explained --- # Roles explained A role is the function an agent performs — and a routing tag, never a model name. Foxora resolves role × tier into a concrete model for you, with provider fallback, so you design with functions and let the platform pick the brains. ## A role is a tag, not a model You never write gpt-4 or claude-x on an agent. You pick a role — what the agent is for — and Foxora maps that role, at the crew’s tier, to the best available model with a fallback chain behind it. When a better model ships, your agents get it without an edit. Models change in the gateway; your agent design doesn’t. > **Why this matters** Pinning a raw model name freezes an agent to one vendor’s current offering. Routing by role keeps the agent on the best brain for its job over time, and lets the same agent run cheaper or stronger just by changing its tier. See Models & tiers. ## The built-in roles Every agent picks exactly one role. Foxora ships a core set, each tuned for a distinct function: - Workhorse — the generalist orchestrator loop; the agent at the center of your workspace that plans, acts, and delegates. - Coding — reads the real code, makes the smallest correct change, and runs to verify. - Reasoner — hard architecture, trade-offs, and deep debugging; the agent you want for the genuinely hard calls. - Research — searches the live web, reads primary sources, synthesizes, and cites. - Scout — a fast, strictly read-only reader that answers where / what / how-it’s-wired for the loop. - Web search — live web search and page fetch for current facts, docs, prices, and news. - Vision — analyzes images, screenshots, mockups, diagrams, and charts. - Utility — cheap, fast triage: summarize, extract, classify, reformat. ## Roles carry doctrine, instructions layer on top A role gives the agent more than a model. It carries Foxora’s managed doctrine — the operating habits for that function (a Scout never writes; a Reasoner shows its trade-offs). The editor shows that doctrine read-only; your instructions are an addendum that personalizes the agent without rewriting the function. ## Custom roles Beyond the core set, your workspace can define its own roles in the Roles registry — same idea, a named function that resolves to a managed model per tier. Any agent can adopt one from the Role picker. > **Override only when you must** You can pin a specific model on an individual agent — managed or your own via BYOK — which overrides the role’s managed routing. Reach for it sparingly; the whole point of roles is that you don’t have to. --- source: https://docs.foxora.ai/agents/models-and-tiers title: Models & tiers --- # Models & tiers Foxora resolves a concrete model from two things: the agent's role and the tier it's running at. Tiers — Fast, Pro, Max — set the class of model; your plan gates which tiers you can use. ## role × tier → a model Two inputs, one model. The agent’s role says what kind of brain it needs; the tier says how capable. Foxora’s gateway combines them — role × tier — into a concrete model, with a provider-fallback chain so a single outage never stalls a run. You never name the model. ## The three tiers - Fast — snappy, low-latency models for everyday tasks. - Pro — the default; strong general-purpose work for serious, multi-step jobs. - Max — the most capable models for your hardest reasoning and trickiest builds. > **Tier names in Settings** In Settings → Models the managed pools read Fast, Premium, and Max — the Pro tier you pick on a crew is the Premium pool. Same thing, two surfaces. ## Tier lives on the crew You usually don’t set a tier per agent — you set it on the crew. A crew is a lineup of agents led by an orchestrator, and the crew’s tier is the pool every member routes at. Foxora ships three built-in crews that share one lineup and differ only by tier: - Foxora Auto — the Fast tier; everyday autonomous work, fast and economical. - Foxora Pro — the Pro tier; stronger reasoning and coding for serious work. - Foxora Max — the Max tier; frontier models for the hardest problems. Switch crews in the composer to move your whole workforce up or down a tier in one move — same agents, same roles, a different class of brain. ## Plans gate the tiers Which tiers you can run is gated by your plan’s feature flags. The Max pool, for instance, is a Max-plan capability. In Settings → Models, pools your plan doesn’t unlock are shown but locked — upgrade to enable them. > **Design for Fast** The Fast tier is the benchmark to design against: if your agent, role, and skills work well there, they only get better at Pro and Max. Reach for a higher tier when you hit a real quality wall, not by default. --- source: https://docs.foxora.ai/agents/byok title: Bring your own keys --- # Bring your own keys Bring your own keys (BYOK) lets an agent run on a specific model from your own provider account — routed through your key, billed to you directly. The managed gateway stays the default; BYOK is the override. ## When to use BYOK Most agents should stay Foxora-managed — you get the best model per role and tier with fallback, and one bill. Reach for BYOK when you need a specific model, an enterprise account with its own rates and data terms, or capacity Foxora doesn't route to. > **Your usage, your rates** With BYOK, calls go through your provider key, so Foxora bills nothing for the model — you pay the provider directly. The managed gateway above it stays the default for every other agent. ## Add a provider in Settings → Models 1. **Open Settings → Models** — Go to Settings → Models. Below the managed pools you'll find Your providers. 2. **Add your key** — Click Add provider, pick a provider (OpenAI, Anthropic, NVIDIA, OpenRouter…), and paste your API key. The gateway routes through it — the key is held by the gateway, never by the app. ## Pin a BYOK model on an agent In the agent editor's Model tab, switch from Foxora-managed to Your own model. The picker lists every model from the providers you've connected; choose one and it's pinned to that agent, overriding the role's managed routing. > **Connect a provider first** If you haven't added a provider yet, the Model tab shows nothing to pick and offers a Connect a provider button that jumps you to Settings. Provider errors (a bad or expired key) surface inline so you can fix them. > **Treat keys like passwords** A provider key grants access to that provider's spend. Add it only in Settings → Models, rotate it if it leaks, and remove it from Foxora when you stop using it. Foxora routes through the key; it doesn't embed it in your agents. --- source: https://docs.foxora.ai/agents/templates title: Templates --- # Templates A template is a pre-wired starting point for a new agent — persona, instructions, tools, and skills already filled in. Pick one, tweak it, and you've skipped the blank-page problem. ## Starting from a template Open Templates in the Agents workbench. Each card describes what it sets up; click Use and the manual editor opens, pre-filled from the template — a fresh id and name, ready for you to adjust and save. Nothing is saved until you do. ## The built-in templates - Blank agent — start from nothing and wire it up yourself (opens an empty editor). - Coding agent — reads, edits, and runs a codebase; seeded with the read / write / edit / bash / lsp tools and the code and debug skills. - Research agent — web search plus synthesis with citations. - Support triage — reads a queue, drafts replies, and escalates cleanly. - QA agent — writes and runs tests, reports failures with repro steps. - Starter crew — a supervised team of agents rather than a single one. See Crews. ## What a template pre-fills A template seeds the editor’s authorable fields — the persona, the instructions, and the attached tools and skills. Everything else (role, model tier, connections) you set as usual. Because it lands in the same editor, you can change anything before saving. > **Template, AI, or scratch** A template is the middle path between Build with AI (describe it, Foxora drafts it) and Start from scratch (a blank editor). Reach for a template when your need matches one of the common shapes; use AI when it doesn’t. > **Save your own (coming)** Templates today are Foxora’s built-in starting points. Authoring and sharing your own templates is on the roadmap — for now, the fastest way to reuse a setup is to duplicate an existing agent and adjust it. --- source: https://docs.foxora.ai/agents/cloud-agents title: Cloud agents --- # Cloud agents Cloud agents are agents Foxora hosts for you. Use them when an agent needs to keep running on a schedule, respond to webhooks, or stay alive when your laptop is closed. ## When to reach for a cloud agent - Daily / hourly summaries (digest emails, KPI reports). - Inbox triage that runs while you sleep. - Webhook responders — e.g. an agent that triages incoming Stripe events. - Long-running workflows that exceed a single chat session. ## Setting one up - Open Dashboard → Cloud agents. - Click + New cloud agent. - Pick a crew and tier, give it instructions, and add the tools it needs. - Choose a trigger: Manual, Schedule (cron), or Webhook. - Save. The agent is live and runs on the next trigger. ## Schedules Cloud agents accept standard cron expressions. A few examples: ```bash # Every hour at :00 0 * * * * # Every weekday at 09:30 30 9 * * 1-5 # First of every month at 06:00 0 6 1 * * ``` ## Webhooks Each webhook-triggered agent gets a unique URL of the form https://api.foxora.ai/v1/agents//invoke. Send a POST with a JSON body and the agent will start processing it. ```bash curl -X POST https://api.foxora.ai/v1/agents/AGENT_ID/invoke \ -H "Authorization: Bearer $FOXORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": "Hello from a webhook" }' ``` ## Logs & debugging Every cloud agent run shows up in Dashboard → Usage with the prompt, the tool calls it made, and the final output. Failed runs keep their error trace for 30 days. > **Concurrency limits** Free plans run one cloud agent at a time. Pro and Team plans get progressively higher concurrency. See Plans & pricing. --- source: https://docs.foxora.ai/crews/overview title: Crews overview --- # Crews overview A crew is a small organization: one lead agent orchestrating a team of agents, each with a role, all working toward a mission. Pick a crew in the composer and the lead plans the work, delegates to the right teammate, and integrates the results. ![Crews overview — screenshot placeholder](placeholder) ## What a crew is A single agent is one specialist with one brain. A crew is a team of them with a chain of command. It has four parts: - A lead — the supervising agent. It orchestrates: it plans, hands scoped work to the right teammate, and stitches the pieces back together. It never tries to do everything alone. - A team — the other agents in the lineup. Each is a full agent with its own skills and tools, and each gets a role in this crew (Engineer, Reviewer, Researcher…). - A mission and goal — why the crew exists, and the objective the lead drives the team toward. Both are woven into the lead’s brief. - A tier — the gateway pool every member runs at. One knob shifts the whole crew between Fast, Premium, and Max. ## Tiers, not models A crew runs at one of three tiers — Fast, Premium, or Max. The tier isn’t a model name; it’s a gateway pool. Each member resolves its own model from its role times the crew’s tier, through the gateway. Move the tier up and every seat upgrades together — you never pin a model yourself. - Fast — quick answers and everyday tasks; the lead’s edge is routing and momentum. - Premium — serious build work, premium models per role. - Max — the hardest problems, frontier models at every seat. > **Built-in tier crews** Foxora ships three built-in crews — Fast, Pro, and Max — that pair the full specialist lineup with a tier and a tuned orchestration style. They’re a great default before you build your own. ## A crew vs. a single agent Reach for a crew when the work has more than one shape: - Use a single agent when the task is one specialty end to end — a focused edit, a piece of research, one document. - Use a crew when a job spans specialties or splits into parallel parts — plan and build and review a feature; research, draft, then fact-check. The lead breaks it down and runs the team. Because each teammate is a real agent, a crew’s capabilities are just its members’ capabilities. To change what a crew can do, edit its agents — their skills and connections carry through. --- source: https://docs.foxora.ai/crews/building title: Build a crew --- # Build a crew Build a crew like you'd build a team: name it and give it a mission and goal, pick the lead, add teammates and assign each a role, choose the tier, and toggle it into the composer. An org chart updates live as you go. ## Open the crew builder Go to Workbench → Crews and click New crew. The builder opens with the form on the left and a live org-chart preview on the right. ## Build it, step by step 1. **Name it, and set the mission and goal** — Give the crew a name (it has to be unique). Then write its mission — why this organization exists — and its goal — the objective the lead drives the team toward. Both feed straight into the lead's brief, so be concrete: "Ship the feature with tests and a clean diff." 2. **Pick the lead** — In Lead, click the agent that should orchestrate the crew. The lead plans the work and delegates — it doesn't do everything itself. An agent can't be both the lead and a teammate, so picking a lead removes it from the team list automatically. 3. **Add the team and assign roles** — Under Team, toggle in the agents you want. Each one you add gets a row with a role field — type what it does in this crew (Engineer, Reviewer, Researcher). The same agent can play different roles in different crews; the role is per-member, not baked into the agent. See Roles and routing. 4. **Set the tier** — Choose Fast, Premium, or Max. The crew runs every member at this tier, and each member's role times the tier resolves its model through the gateway. One knob moves the whole crew up or down a gear — you never name a model. 5. **Show it in the composer** — Flip Show in composer on to make the crew live. Once live, it appears as a pick in your session composer, ready to run. Leave it off while you're still shaping it. ## The org-chart preview As you edit, the preview on the right renders the crew as an organization — the lead crowned and accented at the top, a connector down to the team, and each teammate as an avatar card showing its name and role. It's the fastest way to sanity-check the shape: is the right agent leading, and does everyone have a job? > **Edit capabilities on the agents** A crew has no separate skill or tool list — its capabilities are its members'. To give a crew a new ability, add the skill or connection to one of its agents. > **Click Save crew** Save when the name is set and unique. The crew is stored to your memory den and, if it's live, becomes a supervisor you can pick in any new session. --- source: https://docs.foxora.ai/skills/overview title: Skills overview --- # Skills overview A skill is a reusable playbook an agent loads on demand. Instead of stuffing every how-to into an agent's prompt, you write the procedure once as a skill — and the agent pulls it in only when the task calls for it. ![Skills overview — screenshot placeholder](placeholder) ## What a skill is A skill is an instruction pack — a markdown playbook that tells an agent how to do something well. When an agent hits a task that matches, it loads the skill (with use_skill) and follows the steps, without you bloating its base prompt. Think of it as a procedure the agent can look up the moment it needs it. Each skill carries a little more than just text: - A SKILL.md body — the actual how-to the agent reads. - Granted tools — the tools the playbook expects to use. - Scripts — named commands the skill can run in the sandbox. - Identity — an icon, name, description, version, tags, and a palace locus. ## Built-in vs. custom The library groups skills into two kinds, with an All / Built-in / Custom filter: - Built-in — Foxora’s own playbooks, managed for you. They’re shown read-only and abstract: you see the name, description, and what they grant, but never the SKILL.md body or scripts. - Custom — the skills you write. These get the full editor: identity, granted tools, scripts, and the SKILL.md body. Skills are discovered from your project and global skill folders, so a skill you write for one project can be shared across your machine. > **Skills sharpen agents; tools enable them** A skill is know-how (a playbook). A tool is a capability (executable code). A skill often grants the tools it relies on — see the tools catalog. --- source: https://docs.foxora.ai/skills/creating title: Create a skill --- # Create a skill A custom skill is yours to author end to end: give it an identity, grant it the tools it needs, add any scripts it runs, and write the SKILL.md body that an agent reads when it loads the skill. ## Open the skill editor Go to Workbench → Skills and click New skill. The full-page editor opens with four sections: Identity, Capabilities, Scripts, and Instructions. ## Identity 1. **Icon and name** — Pick an icon and give the skill a name (it must be unique). The name shows on the card and in each agent's skill index. 2. **Description, version, and tags** — Write a one-line description — this is what an agent sees when deciding whether to load the skill, so make it match-worthy. Set a version (e.g. 1.0.0) and add comma-separated tags like dev, review for filtering. 3. **Locus** — Set a locus — a palace address for capability scoping, like work.skills.review. It places the skill in your memory den so it can be scoped and found by address. ## Capabilities — granted tools In Capabilities, select the tools the skill expects to use. These come from the same read-only catalog the rest of the app draws on — you grant existing tools, you don't invent new ones here. See the tools catalog for what's available and how connecting apps adds more. ## Scripts Add scripts — named commands the skill can run in the sandbox. Each script has a name, a command (e.g. bun run check), and an optional description. They give the playbook repeatable, one-call actions instead of the agent retyping a command each time. ## The SKILL.md body Finally, write the Instructions — the SKILL.md body, in markdown. This is exactly what use_skill discloses to the agent when it loads the skill, so write it as a clear procedure: Keep it actionable — numbered steps, what to check, what "done" means. A tight playbook is what lets a Fast-tier agent punch above its weight. Click Create skill when you're done. > **Built-in skills are read-only** You can open a built-in skill to see what it does and what it grants, but its body and scripts are managed by Foxora. Only custom skills get the full editor. --- source: https://docs.foxora.ai/skills/tools title: The tools catalog --- # The tools catalog Tools are the capabilities your agents act with. The catalog is read-only — a tool is executable code, so it isn't authored in the app. You connect new tools by linking MCP servers and apps; agents and skills then pick which ones to use. ## A read-only catalog Open Workbench → Tools to browse every tool available to your agents, grouped by capability and searchable. You don’t create tools here — a tool is executable code. Instead, agents and skills select which tools to use, and you add capability by connecting MCP servers and apps. ## Where tools come from Every tool in the catalog traces back to one of four sources: - Built-in — Foxora’s first-party tools: web search and fetch, vision, planning (todo_write), skills (use_skill), orchestration (task, ask_user), memory, and browser/OS reach. - Workspace — the jailed filesystem, search, shell, and code-intel tools from the Mastra workspace (read, edit, grep, bash…). Discovery runs through bash, so there’s no separate file-finder tool. - MCP — tools exposed by any MCP server you connect. - Connections — tools that appear when you link an app (Slack, GitHub, Notion…) in an agent’s Connections. ## Approval levels Each tool carries an approval level that decides whether it can run on its own or needs your sign-off — this is what your autonomy setting acts on: - Read — safe, no approval. Reading a file, searching, fetching a URL, inspecting symbols. These just observe. - Write — changes files. write and edit render a diff and are gated when you’re on Ask first. - Execute — runs commands or destructive actions: bash, delete_file, stopping a process, delegating a sub-task. The most guarded tier. ## Adding tools by connecting apps Because the catalog is read-only, the way you give agents new powers is to connect them. Link an MCP server or an app from an agent’s Connections tab, and its tools flow into the catalog as live tools — ready for that agent to use, and grantable to your skills. > **Skills and tools, together** When you author a custom skill, you grant it tools from this same catalog. Connect the app first, then grant the tool — the skill and the agent both see it. --- source: https://docs.foxora.ai/connections/overview title: Connections --- # Connections Connections give your agents hands. Link an app once and its tools show up in every session — read a GitHub issue, query Postgres, deploy to Vercel, post to Slack. Foxora keeps three kinds of connection cleanly apart so a model key never gets confused with a tool server. ![Connections — screenshot placeholder](placeholder) ## Three kinds of connection Foxora deliberately separates three things that look similar but behave differently. Mixing them up — the classic mistake — means a model key gets treated as a tool server, or a chat platform as a model. Each lives in its own place in Settings. - Connectors — MCP tool servers. Connecting one (GitHub, Postgres, Linear, Sentry…) hands your agents that app’s tools. This is the Connections section. - Model providers — bring-your-own API keys (OpenAI, Anthropic, Mistral…). A key makes those models routable through the gateway on your account — it is not a tool. Lives under Model providers. - Channels — messaging platforms (Slack, Discord, Telegram, email…) where a crew can operate. These run on Foxora’s hosted side and route inbound messages to an agent. ## How a connection becomes a tool A connector is a curated entry in Foxora’s catalog. The catalog owns the command that launches each app’s MCP server — you only ever supply config (a token, a connection string). That split is the security boundary: a stored value can fill an env var, but it can never choose which binary runs. When a session starts, every active connection resolves into a running MCP server over stdio, and its tools are merged into the agent’s toolbelt — namespaced per app, so a Notion tool can’t be mistaken for a Postgres one. A half-configured connection is simply skipped, never launched broken. > **Encrypted server-side** When you save a connection, the config (tokens, keys, connection strings) is sent to the gateway and encrypted there. The desktop app holds the form values only long enough to submit them. --- source: https://docs.foxora.ai/connections/connecting title: Connecting an app --- # Connecting an app Connect an app from Settings → Connections. Browse the catalog by category, pick an app, then connect it the way it supports — a one-click OAuth handshake, your own OAuth app, or by pasting an API key. ## Browse by category 1. **Open Connections** — Open Settings (⌘, / Ctrl+,) → Connections. You'll see your connected apps; click Add connection to browse the catalog. 2. **Find an app** — Apps are grouped into categories — Development, Databases, AI & Search, Deployment & Cloud, Productivity, Automation, and Monitoring. Use the search box to filter by name or description. Apps you've already connected show a check; apps that support a hosted handshake show an OAuth tag. 3. **Pick it** — Click an app to open its config form. The form shows exactly the fields that app needs — some need none at all. ## Three ways to connect Which controls appear depends on the connector. Foxora picks the most convenient method an app supports and falls back gracefully. ### One-click OAuth When an app supports a Foxora-hosted OAuth handshake, you get a Connect with… button — no token to paste. Click it and the app opens in your browser to authorize. The panel shows "Waiting for authorization in your browser…" and polls until the connection lands, then drops you back to the list. ### Your own OAuth app (Google / Microsoft) For Google and Microsoft apps where Foxora-hosted OAuth isn't set up, you can authorize with your own OAuth app: - **Google** — paste your Google Cloud OAuth client JSON (a Desktop app client), then click Authorize. Add `http://127.0.0.1:9787/auth/callback` as a redirect URI in Google Cloud Console first. - **Microsoft** — enter your Azure app's client ID and client secret (and optionally a tenant ID), add the same loopback redirect URI, then click Authorize. Some Google connectors (Gmail, Calendar, Drive) instead take a service-account or OAuth-client JSON that the MCP server itself authorizes on first use — you paste the JSON, and the browser consent happens the first time the agent uses it. ### API key or connection string Most connectors just need a credential pasted into a field — a personal access token, an API key, or a database connection string. Each field carries a Get it → link to where you generate the value. Click Connect when the form validates. > **No credentials needed** Some connectors — like the project-jailed File System and Git servers, or Docker and Playwright — need no config at all. The form simply says "No credentials needed — just connect." > **Update or remove anytime** Re-opening a connected app shows Update connection. In the list, hover a row to reveal the remove button. Removing a connection pulls its tools from future sessions. --- source: https://docs.foxora.ai/connections/catalog title: The connector catalog --- # The connector catalog The connector catalog grouped by category, with representative apps in each. Every connector is a curated MCP tool server — Foxora owns the launch command, you supply only the credentials. ## Development Source control, repos, and local dev tooling. - GitHub, GitLab, Azure DevOps — repos, issues, PRs, pipelines. - Git & File System — jailed to the open project, no config. - Docker, Context7 — containers and up-to-date code docs. ## Databases Query and manage relational, document, cache, and search stores. - PostgreSQL, MySQL, SQLite, Snowflake — connection-string or credential based. - MongoDB, Redis, Neon, Supabase. - Elasticsearch, Chroma — search and vectors. ## AI & Search Web search, retrieval, and agent infrastructure. - Exa, Tavily — neural / LLM-tuned web search. - Pinecone, Qdrant — vector indexes. - Memory, Sequential Thinking — knowledge-graph and reasoning scaffolds. ## Deployment & Cloud Ship code and operate infrastructure. - Vercel, Netlify, Render, Cloudflare. - AWS, Google Cloud, Firebase, Kubernetes, Terraform. ## Productivity Docs, issues, CRM, payments, and design. - Notion, Linear, Jira, Asana, Trello, Todoist. - Stripe, HubSpot, Airtable, Shopify, Figma. - Gmail, Google Calendar, Google Drive — OAuth. ## Automation Browsers, scraping, and meta-connectors that front many apps. - Playwright, Puppeteer — drive headless browsers. - Firecrawl, Apify, Brave Search, YouTube, Google Maps. - Composio, Zapier — one connection that fronts hundreds-to-thousands of app actions via your own MCP endpoint. ## Monitoring Errors, metrics, dashboards, and product analytics. - Sentry, Datadog, Grafana, PostHog. > **Don't see your app?** Reach almost anything through the meta-connectors. Composio and Zapier mint a per-account MCP URL that fronts hundreds-to-thousands of app actions — paste the URL and connect once. See adding an MCP server for arbitrary servers. --- source: https://docs.foxora.ai/connections/channels title: Channels --- # Channels Channels deploy a crew where the business talks — Slack, Discord, Telegram, email, and more. Unlike connectors (which hand an agent tools), a channel is a place an agent operates: it routes inbound messages to a crew and replies in-platform. > **Channel wiring is being finalized** Channels run on Foxora's hosted side — localhost can't receive inbound webhooks, so the platform adapters and message routing live in the cloud. Connecting a platform and storing its credentials works today; the final step of routing a channel to a specific crew is still being finalized. Expect this flow to tighten in an upcoming release. ## The platforms Channels are grouped by where the conversation happens: - **Team chat** — Slack, Discord, Microsoft Teams, Google Chat. - **Customer messaging** — WhatsApp Business, Messenger. - **Email** — Gmail, Outlook / Microsoft 365, or any provider via SMTP / IMAP. - **Developer** — GitHub and Linear (operate on issues and PRs in-platform). - **Voice & SMS** — Twilio SMS. ## Connect a platform 1. **Open Channels** — Open Settings → Channels and click Add channel. Pick a platform from team chat, customer messaging, email, or voice. 2. **Enter platform credentials** — Each platform asks for its own credentials — a Slack bot token and signing secret, a Telegram bot token from @BotFather, a Twilio account SID and number, and so on. Optional webhook secrets verify inbound updates. 3. **Route it to a crew (coming soon)** — Once routing lands, you'll point the connected channel at the crew that should answer there. Until then, the credentials are stored and ready. > **Channels vs. connectors** A connector gives an agent a tool (e.g. Slack-the-tool to post a message). A channel is where an agent lives — it listens to a platform and replies there. The same app can appear in both lists for the two different jobs. --- source: https://docs.foxora.ai/connections/using-tools title: Using connected tools --- # Using connected tools A connection's tools are available to your agents automatically — but you decide which agent gets which. The agent editor's Connections tab lets you enable or disable each connected app per agent. ## Available to every session Tools from an active connection are merged into the agent toolbelt when a session starts — you don’t re-connect per project. Each app’s tools are namespaced under its name, so the agent sees, say, github_* tools distinct from linear_* tools. ## Per-agent enable / disable Not every agent should reach every app. Open an agent in the editor and go to its Connections tab to toggle which connected apps that agent can use. A reviewer agent might get GitHub and Sentry but not your database; a data analyst the reverse. See the agent editor for the full set of tabs, and Tools & skills for how connected tools sit alongside built-in tools and skills. > **Least privilege** Give each agent only the connections it needs. Fewer tools means a sharper, faster-deciding agent — and a smaller blast radius if something goes wrong. > **Half-configured? Skipped.** If a connection is missing required config, its server simply doesn’t launch and its tools don’t appear — the rest of your tools are unaffected. Re-open the connection to finish configuring it. --- source: https://docs.foxora.ai/mcp/overview title: MCP --- # MCP The Model Context Protocol (MCP) is the open standard for connecting AI apps to tools. Foxora speaks it in both directions: it can be an MCP server other apps plug into, and it can add other MCP servers as connectors so their tools flow into your agents. ![MCP — screenshot placeholder](placeholder) ## What MCP is MCP is a small, open protocol that lets an AI application talk to external servers that expose tools, resources, and prompts. Instead of every app hard-wiring every integration, a server published once works in any MCP-aware client. Foxora is MCP-native: connectors are MCP servers, and Foxora itself is an MCP server. ## The two directions ### 1 · Foxora as an MCP server Expose a small, safe slice of Foxora’s tools to other apps. Add Foxora to Claude Desktop, Cursor, or any MCP client and those apps can read files, search, and fetch the web through Foxora. Covered in Foxora as an MCP server. ### 2 · MCP servers as connectors Go the other way: add an external MCP server so its tools become part of your agents’ toolbelt. Foxora’s whole connector catalog is built on this — and meta-connectors like Composio and Zapier let you point at any MCP URL. Covered in Adding an MCP server. > **One protocol, two roles** The same standard powers both: when Foxora is the server, another app is the client; when a connector is the server, Foxora is the client. See Connections for how connectors become agent tools. --- source: https://docs.foxora.ai/mcp/foxora-as-server title: Foxora as an MCP server --- # Foxora as an MCP server Use Foxora's tools inside other apps. Copy one JSON snippet from Settings → MCP Server into Claude Desktop, Cursor, or any MCP client, and those apps gain a safe, read-only-plus-web slice of Foxora's toolbelt. ## Copy the config 1. **Open the MCP Server section** — Open Settings (⌘, / Ctrl+,) → MCP Server. The Configuration card shows a JSON snippet pointing at your local Foxora engine's `/mcp` endpoint. 2. **Paste it into your MCP client** — Copy the snippet and paste it into the app's MCP config — for example, Claude Desktop → Settings → Developer, or Cursor's MCP settings. The exact endpoint matches your running engine: ```json { "mcpServers": { "foxora": { "url": "http://127.0.0.1:4097/mcp" } } } ``` 3. **Use Foxora's tools** — Restart or reload the MCP client. Foxora now appears as a tool server named foxora, and the app can call the exposed tools below. ## The six web-safe tools Foxora deliberately exposes only a small, read-only-plus-web slice of its toolbelt over MCP: - `read_file` — read a file's contents. - `list_dir` — list a directory. - `find_file` — locate files by name. - `grep` — search file contents. - `web_search` — search the web. - `web_fetch` — fetch a URL. > **Shell and write are not exposed** The MCP server is read-only and web-only by design. Shell execution and file-writing tools are deliberately not exposed — an outside app talking to Foxora over MCP can inspect and search, but cannot run commands or modify your files. To let an agent act, build it inside Foxora instead. > **Local endpoint** The URL in the snippet points at your machine's Foxora engine (the local `/mcp` endpoint). It works while Foxora is running on that device — copy the exact value the Settings card shows rather than hardcoding a port. --- source: https://docs.foxora.ai/mcp/adding-servers title: Adding an MCP server --- # Adding an MCP server Going the other direction: add an external MCP server so its tools flow into your Foxora agents. Foxora's entire connector catalog is built on MCP — and meta-connectors let you bring any MCP endpoint you have. ## Catalog connectors are MCP servers Every entry in the connector catalog is an MCP server. Foxora curates the launch command — you supply only the credentials — and on session start it runs the server over stdio and merges its tools into the agent. So “connecting GitHub” is, under the hood, “adding the GitHub MCP server.” ## Bring your own MCP server For servers outside the curated catalog, reach them through a meta-connector. Both accept an MCP server URL you paste: - Composio — create an MCP server in Composio and paste its URL (https://mcp.composio.dev/…). One connection fronts 250+ managed app integrations with OAuth handled for you. - Zapier — generate your Zapier MCP endpoint (https://mcp.zapier.com/api/mcp/…) and paste it. One connection fronts 30,000+ app actions. These bridge a remote MCP server to your agents and run any OAuth flow in the browser on first use — you authorize once. ## Where the tools appear Once connected, an MCP server’s tools behave like any other connection: merged into the agent toolbelt at session start, namespaced under the connection’s name, and toggleable per agent from the agent editor’s Connections tab. See Using connected tools. > **Two ways to extend** To give Foxora more tools, add an MCP server here. To give other apps Foxora’s tools, use Foxora as an MCP server. Same protocol, opposite roles. --- source: https://docs.foxora.ai/memory/overview title: Memory overview --- # Memory overview The Den is Foxora's memory — a persistent store that lets agents remember what matters across sessions, projects, and restarts. It runs as a local service on your machine, organizes everything into a spatial map called the Palace, and keeps a record of why it believes each thing it knows. ![Memory overview — screenshot placeholder](placeholder) ## What the Den is A chat that forgets everything when you close the window isn’t much of an assistant. The Den is what lets Foxora carry context forward: the conventions of your codebase, your preferences, the decisions you made last week, the people and projects you keep coming back to. Agents read from it before they act and write to it as they learn — so the second time you ask for something, Foxora already knows the shape of the answer. Crucially, the Den is local-first. It runs as a small daemon on your own machine (foxmemd, on 127.0.0.1:7777), and your memories live there — not on a server. That’s covered in detail in Local-first & private. ## Why it matters - Continuity — context survives across sessions, projects, and app restarts, so agents don’t start from zero every time. - Personalization — the Den learns how you work — your stack, your style, your recurring people and places — and tailors agents to it. - Grounding — every memory carries a why: the conversation, file, or command it came from. Agents recall facts they can trace, not guesses. - Privacy — because it’s local, your accumulated knowledge stays on your device. ## The four layers Not all memory is the same. The Den sorts what it stores into four layers, from raw detail up to durable understanding: - Raw — verbatim fragments, the unprocessed material an agent saw. - Episodic — events: what happened, when, in a session or a task. - Semantic — distilled facts and preferences (“uses Bun, never npm”). - Relational — the connections between things: how people, projects, and facts relate. Higher layers are more abstract and longer-lived; lower layers are richer and more ephemeral. Recall blends across them so an agent can answer with both the fact and the story behind it. > **Durability, not deletion** Memories also carry a durability class — transient (this task), semester (this stretch of work), or permanent (a standing truth). Confidence and a freshness flag mean the Den can hold a belief loosely and re-check it, rather than treating everything it ever saw as gospel. ## The Palace — a spatial model The Den is spatial-primary: instead of one undifferentiated pile, every memory lives at an address — a dotted locus like work.foxora.kitspace. Those addresses fold into a tree called the Palace, rooted at a fixed set of places: - work — your jobs, projects, and codebases. - life — people, preferences, the personal context. - creative — writing, design, ideas. - learning — what you’re studying and figuring out. - vault — access-locked, for the things that need to stay private. Thinking spatially is what makes a large memory navigable: an agent can recall everything under work.** without trawling unrelated life context, and you can browse your own memory the way you’d browse a filesystem. Walk through it in Explore the Den. > **Memory powers agents and crews** The Den is what agents draw on to stay consistent. Pair it with the agent model and sessions to see how recall flows into a live conversation. --- source: https://docs.foxora.ai/memory/explorer title: Explore the Den --- # Explore the Den The Memory Den explorer lets you browse everything Foxora remembers. The left rail is the Palace — the spatial tree of loci. The right pane is the memories at the place you've selected, each with its full record: durability, confidence, freshness, and the provenance trail that explains why it's there. ## Open the explorer Go to Agents → Memory Den. The header shows a live count of how much is loaded — total memories and distinct loci — next to a status dot telling you whether the Den service is connected. ## The Palace tree The left rail is the Palace — the spatial locus tree. Reserved roots (work, life, creative, learning, vault) are always present, and beneath them sit whatever nested loci your memories have created. Each row shows a count: the number of memories at that locus and everything below it. - Click a folder row to select a locus and list its memories. - Click the chevron to expand or collapse its children. - A lock icon marks the vault — access-locked memory. ## Reading a memory Selecting a locus lists its memories (and its descendants’) in the right pane. Each row is compact but carries the full Den tuple: - Anchor — the short headline of the memory, with its dotted locus beside it. - Content — the fact itself, in a line of detail. - Durability — a tag: Transient, Semester, or Permanent. - Confidence — κ, a 0–1 score of how sure the Den is. - Freshness — a colored dot: fresh, stale, or resolved. - When — a relative timestamp for when it was recorded. ### Fresh, stale, resolved The Den doesn’t assume a memory stays true forever. As your behavior drifts from what a memory asserts, the Den can flag it stale — a signal to re-check rather than trust blindly. Once it’s re-confirmed or superseded, it becomes resolved. Most memories sit fresh. ## The full record & provenance Click any memory to open its full record. Beyond the tuple above you’ll see its layer (raw / episodic / semantic / relational), its tags, and — most importantly — its provenance: the P-DAG trail of why the Den believes this. Provenance nodes point back to the evidence a memory was built from — a conversation, a file, a command, an app, or a capture — each with the source and a reference into it. It’s the audit trail that turns “the agent claimed X” into “the agent learned X from here.” ## Recall across the whole Den The search box above the explorer runs Recall — it sweeps every locus at once, matching on anchor, content, and tags, regardless of where in the Palace a memory lives. It’s the fastest way to find a fact when you don’t remember which place it’s filed under. > **Place a memory by hand** Most memories are written by agents as they work, but you can add one yourself with Place memory — useful for seeding a fact you want every agent to know from the start. --- source: https://docs.foxora.ai/memory/privacy title: Local-first & private --- # Local-first & private The Den is local-first by design. Your memory lives in a service running on your own machine, the vault keeps the most sensitive memories access-locked, and the explorer's status panel tells you exactly what's connected — and what isn't. ## Where your memory lives The Den is a local daemon — foxmemd — that listens on 127.0.0.1:7777, a loopback address that never leaves your device. Agents read and write memory by talking to that local service, not a cloud API. Your accumulated knowledge — the Palace, every memory, every provenance node — is stored on your machine. This is the same principle that governs the rest of your data in Foxora: the things that are yours stay local. For the full picture of what’s on-device versus in the cloud, see Where your data lives. ## The vault Not every memory should be equally reachable. The vault root is access-locked — the explorer marks it with a lock icon, and memories placed there are held to tighter access than the open roots like work or life. Use it for the context you want remembered but guarded: credentials-adjacent notes, private preferences, anything you wouldn’t want an agent to surface casually. > **Scoped access** The Den grants memory access by capability over a locus scope — an agent can be allowed to read work.** while the vault stays off-limits. The vault is the most restrictive end of that model. ## The service status panel Because the Den is a service, the explorer gives you a window into its health. Select Status Info at the top of the Palace rail to open the service panel, which reports: - Service — connected, checking, or unreachable. - Server — the local address the Den is listening on. - Memories stored and Loci — how much the Den holds. - Vector index — whether semantic recall is on (otherwise recall falls back to keyword search). - Version and Last checked — the running build and the freshness of the status. ## Local vs cloud It’s worth being precise about the boundary: - Local — the Den service, your Palace, every memory and its provenance, and the vault all live on your device. - Cloud — agent execution may run in Foxora’s cloud, and embeddings used to power semantic recall are generated through the gateway. The memories those embeddings index, though, stay local. > **One source of truth** Because there’s exactly one Den per device and it’s local, you never have to reconcile two copies of what an agent “knows.” What you see in the explorer is what every agent reads. > **Memory is tied to your device** Local-first cuts both ways: a memory written on one machine lives on that machine. Treat the Den as device-local context, and lean on the data-location guarantees for the full story of what is and isn’t synced. --- source: https://docs.foxora.ai/automation/overview title: Automation overview --- # Automation overview Automation is where your agents stop waiting for you. Put them on a schedule, queue work for them, and watch the runs — durable jobs that keep going even with the app closed. ![Automation overview — screenshot placeholder](placeholder) ## Three surfaces Automation lives in the Workbench and is made of three connected views: - Schedules — the triggers that start a run on their own: a cron cadence, an internal event, or an inbound webhook. See Schedules. - Tasks — a queue of work you assign to an agent or crew, tracked from queued through to done. - Queue & Runs — the operational view: what’s running now, what’s waiting, and the history of what already finished. ## Durable by design A schedule isn’t tied to a window being open. The intent — “run this agent on this cadence” — is durable, so a job can fire and a run can keep going with the app closed. When you reopen Foxora, the queue and run history catch you up on what happened while you were away. > **Early-stage: authoring is real, execution is landing** The Automation authoring surface — creating schedules and tasks, choosing trigger types, toggling them on and off — is built and works today. The end-to-end executor that drives those triggers, and some of the live state shown in Queue & Runs, is still being wired up and is partly sample data for now. Treat schedules and runs as a preview of the model rather than a production scheduler, and don’t depend on a job firing unattended yet. --- source: https://docs.foxora.ai/automation/schedules title: Schedules --- # Schedules A schedule runs an agent automatically — on a cadence, on an event, or on an inbound webhook. Here's how to create one, choose its trigger, and switch it on. ## Create a schedule 1. **Open Schedules** — In the Workbench, go to Automation → Schedules and click New schedule. The full-page schedule editor opens. 2. **Name it and pick who runs** — Give the schedule a clear name — e.g. Morning inbox sweep — and choose the agent or crew that runs when it fires. Crews run at their tier (Fast, Premium, or Max); see Building agents. 3. **Choose a trigger** — The trigger decides what starts the run. Pick one: - **Schedule** — a recurring cron cadence, e.g. Daily · 8:00 or Mon · 9:00. - **Event** — an internal signal, e.g. a file change. - **Webhook** — an inbound HTTP call, e.g. GitHub · pull_request. 4. **Set the cadence** — Fill in the cadence for the trigger you chose — the timing for a Schedule, the event name for an Event, or the hook for a Webhook. Next run shows when it's due to fire next. 5. **Enable it** — Flip the Enabled switch on and save. A disabled schedule is kept but never fires — handy for pausing without losing the setup. You can also toggle a schedule straight from its row in the list. ## How triggers map to runs Every trigger carries the instruction the agent gets when it fires — the prompt that the run starts from. A cron schedule fires on its cadence in your timezone; an event fires when its topic is signalled; a webhook fires on the inbound call. Channels can be the source of those events — see Channels. > **Triggers are authored, not yet fully driven** You can create and enable any trigger type today, but the executor that fires them unattended is still being wired up. Use schedules to model the automation you want; don't rely on one running on its own just yet. --- source: https://docs.foxora.ai/automation/tasks-and-runs title: Tasks & runs --- # Tasks & runs Tasks are the work you hand to an agent or crew; runs are what executing that work looks like. Together they're the queue and the history of everything your agents are doing. ## The task queue Open Automation → Tasks to see work assigned to agents and crews, grouped by state. Click New task to add one. Each task has: - Title & description — what needs to happen, and any acceptance criteria. - Assignee — the agent or crew that owns it. - State — Running, Queued, Blocked, or Done. - Priority — Low, Normal, or High. - When — free text like now, in 2h, or waiting on approval. ### Moving through states Tasks flow from Queued to Running to Done, and can sit in Blocked when they’re waiting on something — an approval, a dependency, a person. High-priority tasks are flagged in the list so the important work stays visible. ## Queue & Runs Open Automation → Queue & Runs for the operational view. It has two tabs: - Active — what’s running now and what’s queued, with a live status dot per run. - History — completed and failed runs, each with the agent, a one-line summary, and how long it took. > **Where runs come from** A run can start from a schedule firing, a task being picked up, or a crew you kick off by hand. Whatever the source, it lands in the same queue — one place to watch everything your agents are doing. > **Run state is partly sample data today** The Tasks and Queue & Runs screens are real UI, but the executor that keeps their live state in sync is still landing — some of what you see is seeded sample data for now. The shapes (states, priorities, history) are final; treat the live numbers as illustrative until the executor is fully wired. --- source: https://docs.foxora.ai/settings/overview title: Settings overview --- # Settings overview Settings is one modal with everything in it — your account, how Foxora looks and sounds, which models and apps it can reach, what it's allowed to do on your machine, and where your data lives. Open it from anywhere with ⌘, (Ctrl+, on Windows and Linux). ![Settings overview — screenshot placeholder](placeholder) ## Opening Settings Press ⌘, (Ctrl+, on Windows and Linux) from anywhere in the app, or pick Settings from your account menu. A large centered panel opens with a section rail down the left and the chosen section’s controls on the right. Press Esc or click outside to close. > **It opens where you need it** Actions elsewhere in the app deep-link straight to the right section — “Connect GitHub,” for example, opens Settings already on Connections. ## The thirteen sections Here’s what each section on the rail is for: - Account — your profile and plan, with links to manage billing on the web and to sign out. - Usage & plan — your credit balance against rolling weekly and monthly limits, plus the plan cards. - Appearance — theme, accent, color scheme, and typeface. See Workspace appearance. - Voice — talk to your agents and have them talk back. See Voice. - Models — the Fast / Premium / Max tiers and your own provider keys. See Models & tiers. - Connections — the apps your agents can act in. See Connections. - Channels — deploy your crew where the business talks. See Channels. - MCP Server — use Foxora’s tools from other apps. See Foxora as an MCP server. - Permissions — the OS capabilities agents may use. See Permissions. - Data — export and import your local data bundle. See Where your data lives. - Advanced — connection probes, the data folder, and reset local preferences. - Keyboard — a reference of every shortcut, grouped by category. - About — the app version and build. > **Every setting has a home** Most onboarding answers map to a section here, so you rarely have to replay the walkthrough — change autonomy from the composer, voice in Voice, apps in Connections. --- source: https://docs.foxora.ai/settings/reference title: Settings reference --- # Settings reference A control-by-control reference for every section of the Settings modal. Each heading below is a section on the rail, in the order it appears. ## Account Shows your avatar, name, email, and a plan badge. Two actions sit below the card: Manage account & billing opens your hosted Foxora dashboard in the system browser, and Sign out clears the local session on this device. Plan, usage, and billing are managed on the web — the app shows them read-only. If you’re not signed in, this section invites you to sign in and offers a link to the dashboard. ## Usage & plan Credits cover everything Foxora does, drawn down against rolling weekly and monthly limits. This section shows: - Your current plan and credit balance — used, remaining, and when it resets. - The rolling usage windows, so you can see how close you are to a limit. - Plan cards with monthly credits, marking your current plan. Every money action is a link out to the web dashboard — the app never takes a payment itself. The balance refetches each time you open Settings, so it reflects credits a background run may have spent. ## Appearance Four controls, applied instantly and saved on this device: - Theme — Dark or Light. - Font — the UI typeface (Inter, Geist, DM, or Hanken). - Scheme — the neutral palette, chosen from a row of swatches (taupe, slate, mauve, olive, and more). - Accent — the highlight color, from a second row of swatches. These are the same controls available from the account menu. Full detail in Workspace appearance. ## Voice Talk to your agents and have them talk back. Speech runs through the Foxora gateway, so it’s plan-gated and minute-tracked — if no voice key is configured on the gateway yet, the section shows a short note and turns on automatically once it’s available. When voice is on you can set: - Enable voice — the master switch for voice input and spoken replies. - Voice — pick the voice your agent speaks in. - Speak replies aloud and a Speed control (0.75× to 1.5×). - Input mode — Push to talk or Hands-free, with a Send right away option for push-to-talk and Noise suppression. - Wake phrase — e.g. “Hey Foxora”; leave blank to disable hands-free wake. More in Voice. ## Models Your default models, always on. Foxora routes each step to the cheapest tier that can do the job, and every call goes through the gateway — no provider keys touch the app. Three tiers are listed, each marked Included or Locked depending on your plan: - Fast — snappy, low-latency models for everyday tasks. - Premium — deeper reasoning for complex, multi-step work. - Max — the most capable models for your hardest work (Max plan). Below the tiers, a Gateway card shows the routed endpoint. Further down, Your providers lets you bring your own API keys (OpenAI, Anthropic, and others) so the gateway can route through your own provider accounts — your usage, your rates. The managed gateway stays the default for every agent. See Models & tiers. > **Tiers, not model names** Foxora names the tier, not the vendor — the underlying models change, and routing is the whole point. You pick how much horsepower a step gets; Foxora picks the model. ## Connections The apps your agents can act in — GitHub, Linear, Notion, and the rest of the connector catalog. Connect a service, and its tools become available to your agents per turn. Manage which are linked, browse the catalog to add more, and disconnect any you no longer want. Full detail in Connections. ## Channels Deploy your crew where the business talks. Connect a platform — team chat, customer messaging, email, voice, or web — then route it to an agent. Channels run on Foxora’s hosted side, so they keep working when the desktop app is closed. Connect Slack, Gmail, Discord, or Telegram to reach your agents there. See Channels. ## MCP Server Use Foxora’s tools inside other apps by adding Foxora as an MCP server in Claude Desktop, Cursor, or any MCP client. The section gives you a ready-to-paste JSON configuration block pointing at the engine’s `/mcp` endpoint, and lists the exposed tools — read-only and web only (file reading, listing, search, and web fetch). Shell and file-writing tools are deliberately not exposed. See Foxora as an MCP server. ## Permissions The OS capabilities your agents may use — granted only when a task needs them, and changeable here anytime. Capabilities are grouped, and each row shows a status and the right action: - Web-grantable capabilities (microphone, camera, notifications) show a live status dot and an Allow button that triggers the browser prompt; once granted they read Allowed. - OS-managed capabilities (screen recording, accessibility, automation, full-disk access) can’t be prompted — an Open Settings button deep-links you straight to the exact system pane. - Capabilities that don’t apply to your current OS read No setup needed. More in Permissions. ## Data Back up or move your local data — agents, crews, roles, skills, schedules, preferences, and more. Each category has a switch (all on by default). Then: - Export selected downloads a JSON bundle of the chosen categories. - Import from file… restores from a bundle, merging into what’s already here — it never wipes existing data. Everything stays on this device; only the file you download leaves it. See Where your data lives. ## Advanced Connection status and local data, in three cards: ### Connection probes A live status row for each endpoint — Engine (cloud), Login, and Gateway — showing the URL plus a dot reading Connected, Unreachable, or Checking…. Services probe their health endpoint; the login page is probed for plain reachability. ### Foxora data folder Everything Foxora keeps on this device — the engine, Memory Den, and your workspace files — lives in `~/.foxora` (`%USERPROFILE%\.foxora` on Windows). A Reveal in Finder / Explorer button opens it. (This card appears only inside the desktop app.) ### Reset local preferences Clears theme, scheme, accent, and font on this device, then reloads. Your account and sessions are untouched. A confirm step guards the reset. > **Reset is local** Resetting preferences clears local choices only. It does not touch your account, your server-side sessions, or your billing. ## Keyboard A reference of every keyboard shortcut, grouped by category, with OS-aware key labels (⌘ on macOS, Ctrl elsewhere). This view is a cheat sheet — the shortcuts themselves work throughout the app. ## About The Foxora mark, the product name, and the running version — the app version when available, otherwise the UI build. A one-line tagline rounds it out: Your operating system for AI agents. --- source: https://docs.foxora.ai/security/permissions title: Granting permissions --- # Granting permissions Agents only reach for a capability when a task needs it — and they can only use what you've granted. Foxora groups capabilities into ones it can request right in the app, and ones only your operating system can hand out. You manage all of them in one place. ## The Permissions panel Open Settings (⌘, / Ctrl+,) → Permissions. Each capability shows what it’s for, a live status dot where one is available, and an action that fits how that capability is granted on your system. Capabilities that don’t apply to your OS simply read “No setup needed.” ## Capabilities Foxora can request These are requested right inside the app. Click Allow and your OS shows its own prompt; once granted, the status dot turns green and the row reads Allowed. If you previously denied one, the button becomes Open Settings so you can reverse it. - Microphone — voice chat with your agent. - Camera — tasks that need to see your camera. - Notifications — agent updates and task completions. > **The prompt comes from your OS** Foxora never fakes a permission. Clicking Allow simply triggers the real system prompt — the decision is always yours, made through your operating system. ## Capabilities your OS manages Some capabilities are too powerful for an app to request — your OS reserves them for its own settings. Foxora can’t prompt for these, so instead it deep-links you straight to the exact pane with an Open Settings button, and explains why the agent would want it. - Screen Recording — the computer agent sees your screen to act on it. - Accessibility (control) — control mouse & keyboard so the agent can act for you. - Automation — drive other apps to complete cross-app tasks. - Full Disk Access — read & write files anywhere on your machine. ## It differs by operating system The same capability is a different beast on each platform, so Foxora only shows what actually gates on your system: - **macOS** — The strictest. Screen Recording, Accessibility, Automation, Input Monitoring, and Full Disk Access are all macOS privacy gates — Foxora deep-links each one to System Settings → Privacy & Security. - **Windows** — Microphone, Camera, and Notifications are requestable in-app and also link to Settings → Privacy. Screen capture and app control need no separate gate, so those rows read “No setup needed.” - **Linux** — Screen Recording on Wayland is granted through a desktop portal; the mac-specific control gates don’t apply and show as no setup needed. > **Grant only what you're comfortable with** You never have to grant everything up front. Leave a capability off, and the first task that needs it will tell you — then you can grant it here in seconds. Approving an individual action is separate; see approving agent actions. --- source: https://docs.foxora.ai/security/data-location title: Where your data lives --- # Where your data lives Your projects, chats, and memory live in a folder on your own machine — not on a server. Here's exactly where that is on each OS, what stays local versus what touches the cloud, and how to export, reveal, or clear it. ## The data folder Everything Foxora keeps about your work lives in a single home folder on your device: - macOS & Linux — `~/.foxora` - Windows — `%USERPROFILE%\.foxora` That folder holds your sessions and chat history, your memory den, and local settings — the durable record of how you work with Foxora. ## Local versus cloud Foxora is local-first by design. Your data stays on your machine; the cloud is used only to run the model and route requests: - Stays local — your files, sessions, chat history, and the memory den. These never leave your device unless you choose to share them. - Goes to the cloud — the prompt and context an agent needs for a single turn travel to the model gateway to generate a response, then the result comes back to you. > **Memory is local, too** What an agent remembers about you lives in your local den, not on a server. The controls for what’s remembered and what to forget are in memory privacy. ## Revealing the folder To inspect the folder yourself, open Settings (⌘, / Ctrl+,) → Advanced and use Reveal data folder. It opens `~/.foxora` in your file manager so you can see exactly what’s stored. ## Exporting and clearing - **Export your data** — From Settings → Data → Export, Foxora bundles your local data so you can back it up or move it to another machine. Because it already lives in `~/.foxora`, there’s nothing to download from a server — it’s all on your disk. - **Clear your data** — Settings → Data → Clear wipes the local store — sessions, history, and memory. This is a local action: it doesn’t touch your account, billing, or anything on the server. A separate Reset in Settings → Advanced returns local preferences (theme, onboarding state) to defaults. > **Clearing is permanent** Clearing your data can’t be undone. If there’s anything you want to keep, Export first, then clear. --- source: https://docs.foxora.ai/security/sign-in-security title: How sign-in is secured --- # How sign-in is secured Foxora's desktop sign-in is gold-standard native OAuth: PKCE end to end, with tokens that never ride inside a link. Here's what that protects you from, and how your session stays fresh without ever interrupting a long agent run. ## PKCE, end to end When you sign in with Google or GitHub on the desktop, Foxora uses PKCE (Proof Key for Code Exchange). The app generates a one-time secret, opens your real system browser to authorize, and only a short-lived code comes back — which the app then exchanges for a session using that secret. An intercepted code is useless to anyone without it. ## Tokens never travel in a link The redirect that returns from your browser — whether to the app’s one-time loopback listener on 127.0.0.1 or via the foxora:// deep link — carries only the PKCE code, never an access token. Your session is never embedded in a URL that could be logged, cached, or shoulder-surfed. > **The same promise on password reset** A reset link works the same way: it opens a secure page where you set a new password, but the link itself never carries your session. See signing in for the full flow. ## Automatic refresh Once you’re in, Foxora keeps your session alive in the background so a long agent run never dies on an expired token. It force-refreshes the access token before it’s near expiry on two triggers: - On focus — whenever the window regains focus, the session is re-synced. - On a keep-alive timer — a short recurring tick refreshes the token before it can lapse mid-task. ## Device token mirroring Your agents run through a local runtime that talks to the model gateway on your behalf. For that, Foxora mirrors your access token to the local daemon as its gateway credential — and re-mirrors a fresh one every time the token refreshes, so the daemon never holds a stale token that would fail every gateway call. - The mirrored token stays on your device — it’s the local runtime’s key to the gateway. - Each machine and CLI you authorize gets its own mirrored token, refreshed automatically. - Signing out clears the local session and the mirrored token. > **Lost a device?** Because each device holds its own token, you can revoke any one of them. Sign out on the device if you have it, or remove it from the web dashboard — see signing in and the Settings reference. The principle running through all of this: your credentials stay on your machine, and nothing sensitive is ever passed around in a link. --- source: https://docs.foxora.ai/notifications/overview title: Notifications --- # Notifications Foxora keeps you informed without getting in your way. Quick toasts surface what just happened, the Notification Center keeps the durable record, OS notifications reach you when you've stepped away, and attention prompts stop the line when an agent genuinely needs a decision from you. ![Notifications — screenshot placeholder](placeholder) ## Toasts: what just happened Toasts are the small cards that slide in (by default, bottom-right) to tell you something in the moment — a task finished, a command failed, a suggestion is ready. The card itself is calm and monochrome; the only colour is the icon that signals how much it matters: - Success — a task completed; clears on its own after a few seconds. - Error — something failed; stays until you deal with it. - Suggestion — the agent proposes a change; stays so you can act. - Warning · Info · Notice — lighter updates that auto-dismiss. The stack is deliberately quiet. Only a few toasts show at once; the oldest transient ones step aside under pressure, while anything you must act on — errors, suggestions, running tasks — is never pushed out. Repeats of the same event coalesce into one card with an ×N count instead of stacking up. ### Live, process-aware toasts When an agent kicks off real work, the toast becomes a live status card: a spinner, an elapsed timer, and a progress bar that fills as the work proceeds. The same card then morphs in place into a success or error when it’s done — no second notification, just the one card following the task through its life. Long-running tasks can show a Cancel affordance while they run. ## The Notification Center Toasts are ephemeral; the Notification Center is the durable record. The bell in the sidebar footer carries an unread badge, and opening it shows recent notifications — every toast that has left the stack, persisted across reloads. Opening the Center marks everything read and clears the badge. - Each row shows the kind icon, title, and a compact relative time (now, 5m, 2h, 3d). - Rows that had an action stay clickable, so you can act on something you missed. - You can mark all read, remove a single entry, or clear the whole history. ## OS notifications when you're away When Foxora isn’t the focused window, the things that matter follow you out to the operating system. An error, or anything an agent is waiting on, raises a native OS notification — and on macOS, bounces the dock icon and sets a badge count of how many items need you. Focusing the window cancels the bounce. Better still, the toast’s buttons ride along as native notification buttons. Clicking Approve or Decline from the OS notification runs the same action as clicking it in-app — the window focuses, and your choice is applied. > **You decide if OS notifications fire** Native notifications need the notifications permission. Grant or revoke it any time from Settings → Permissions — without it, Foxora simply keeps everything in-app. ## Attention: when an agent needs you Some moments aren’t just updates — the agent has hit a real fork and needs your call: approve a risky command, answer a question, confirm a plan. Foxora marks these as attention prompts, and they behave differently from ordinary notifications: - They’re never auto-dismissed — they wait for you. - They count toward the dock badge and, while you’re away, bounce the icon until you’re back. - They carry the decision buttons — in the toast, in the Center, and on the OS notification. This is the human-in-the-loop bridge: the agent keeps working until it reaches a decision only you should make, then surfaces it everywhere you might be looking and waits. Most of these come from action approvals — see approving agent actions for how those prompts work and how to tune how often they appear. > **Tune the noise** Raising an agent’s autonomy means fewer attention prompts; lowering it means more. The notifications themselves are always honest about what happened — adjust the flow from the composer’s autonomy control, and the OS reach from Settings. --- source: https://docs.foxora.ai/cli/overview title: CLI overview --- # CLI overview The Foxora CLI is the agent terminal — a fast, native command-line client that runs the same crews of agents as the desktop app, straight from your shell. Type foxora to open the interactive UI, or drive it headless with subcommands like run, sessions, and doctor. ![CLI overview — screenshot placeholder](placeholder) ## What the CLI is foxora is the command-line client for Foxora. On first run it provisions the Foxora Runtime (the agent engine, Memory Den, and a workspace) into a per-user cache and runs everything locally — model calls route through the Foxora gateway, so no provider API keys ever live on your machine. Run with no arguments and it opens a full-screen terminal UI. Pass a subcommand and it runs headless, printing to stdout like any other CLI — perfect for scripts, CI, and quick one-shots. ## When to use it - You live in the terminal — drive agents without leaving your shell. - One-shot prompts — foxora run "summarize this repo" streams a reply and exits. - Scripting & CI — the headless subcommands print plain text you can pipe. - Headless boxes — no desktop app required; the CLI provisions its own runtime. The CLI shares one account, one set of sessions, and one data home (~/.foxora) with Foxora Desktop and app.foxora.ai. Sign in once on any surface and the others follow. > **This track targets v5.0.3** Commands, flags, and output shown here describe the foxora CLI as of v5.0.3. Check your version any time with `foxora --version`, and keep it current with `foxora update`. ## Core concepts ### Runtime The engine + memory + workspace bundle the CLI installs into ~/.foxora/runtime. foxora setup provisions it; foxora doctor tells you whether it’s healthy. ### Crew (tier) A crew is a tier of agents — fast, pro, or max — that plan, act, and verify their own work. You can pick a tier per run; otherwise the CLI routes for you. ### Session Each conversation is a session, stored in your data home and shared with every Foxora surface. List them with foxora sessions. --- source: https://docs.foxora.ai/cli/install title: Install the CLI --- # Install the CLI Install the foxora command with the package manager you already use — npm, Homebrew, Scoop, or a one-line install script. Every method drops the foxora binary on your PATH and provisions the runtime on first use. ## Install the foxora command Pick the tab that matches how you like to install tools. **npm** ```bash # any OS with Node 16+ npm install -g foxora ``` Not on your PATH yet? The script installers fall back to `~/.local/bin` when a system dir isn't writable. If your shell can't find foxora afterwards, add that directory to your PATH and restart the shell — the installer prints the exact line to add. 1. **Provision the runtime** — The first time you run anything, Foxora fetches the runtime (engine, memory, workspace, and a bundled bun) into `~/.foxora/runtime`. You can trigger it explicitly: ```bash foxora setup ``` `foxora setup` — provisioning the engine · memory · workspace · bun 2. **Verify the install** — Confirm the binary is on your PATH and print its version: ```bash foxora --version # → foxora 5.0.3 ``` Then run a full diagnostic — it checks the platform, the runtime, the engine, your account, and the gateway in one shot: ```bash foxora doctor ``` ## Keep it current `foxora update` updates the CLI and keeps the runtime matched. It is channel-aware: if you installed through a package manager it points you at the right upgrade command instead of fighting it. ```bash foxora update ``` > **Next: sign in** With the CLI installed, the next step is to authorize it against your account so it can reach the gateway on your behalf. --- source: https://docs.foxora.ai/cli/auth title: Authorize the CLI --- # Authorize the CLI Authorize the CLI with the device-authorization flow — the same model as the GitHub CLI. Foxora shows a short code and a link, you approve in your browser, and the CLI is signed in. No password is ever typed into the terminal. ## Sign in 1. **Start the device flow** — Run the login command: ```bash foxora login ``` The CLI requests a short-lived user code from the gateway, prints a verification link (and copies it to your clipboard), then opens your default browser to app.foxora.ai/activate. Enter code · ABCD-1234 — `foxora login` shows the user code in the terminal. 2. **Approve in your browser** — Sign in (or sign up) at app.foxora.ai and confirm that the code on screen matches the one in your terminal, then approve. Meanwhile the terminal shows "waiting for approval…" and polls until you're done. 3. **You're signed in** — Once you approve, the CLI prints "signed in as you@example.com" and stores your tokens (mode 0600) in `~/.foxora/cli-auth.json` — the same credentials file the desktop app uses, so the surfaces interoperate. A stale access token is refreshed automatically on the next run. ## Check who you are Confirm the signed-in account at any time: ```bash foxora whoami # → ● signed in as you@example.com ``` ## Sign out `foxora logout` removes the local credentials file. Your account and sessions are untouched — you just need to sign in again to make gateway calls from this machine. ```bash foxora logout ``` > **One account, every surface** The CLI, Foxora Desktop, and the web dashboard share one sign-in. If you only ever used Continue with Google or GitHub, that's fine — the device flow signs you in through the same hosted login page. See Accounts & sign-in. --- source: https://docs.foxora.ai/cli/commands title: Command reference --- # Command reference The full command surface. Run foxora with no arguments to open the interactive UI; every subcommand below runs headless and prints to stdout. Use foxora --help for the same list in your terminal. ## Open the interactive UI With no subcommand, foxora launches the full-screen agent terminal. Add --remote to attach to a running engine instead of spawning one. ```bash foxora # open the interactive UI foxora --remote # attach to a running engine, never spawn ``` ## Set up & update ### foxora setup Provisions the runtime (engine · memory · workspace · bun) into ~/.foxora. ```bash foxora setup ``` ### foxora update Updates the CLI and keeps the runtime matched (channel-aware). ```bash foxora update ``` ## Account ### foxora login · logout Sign in with the device-authorization flow, or clear local credentials. ```bash foxora login foxora logout ``` ### foxora whoami Show the signed-in account. ```bash foxora whoami # → ● signed in as you@example.com ``` ## Run a prompt ### foxora run One-shot: send a single prompt and stream the reply to stdout, then exit. Pass an optional crew tier (fast, pro, or max) first; the prompt can be positional or via -n / --prompt. ```bash foxora run "summarize this repo" foxora run fast -n "fix the failing test" foxora run max --prompt "draft a migration plan" ``` ## List your work ### foxora sessions · crews · agents Headless lists of your sessions, crews, and agents. ```bash foxora sessions # list sessions foxora crews # list crews foxora agents # list agents ``` ## Usage & models ### foxora usage Your credit balance and the rolling weekly + monthly windows. ```bash foxora usage ``` ### foxora models List the routable tiers / models available to your account. ```bash foxora models ``` ## Diagnose ### foxora doctor Cross-OS diagnostics — checks platform, runtime, engine, account, and gateway in one pass. Run this first whenever something feels off. ```bash foxora doctor ``` ## Options & environment Global flags work alongside any command: ```bash -n, --prompt the prompt for `run` --remote attach to a running engine, never spawn -h, --help show help -v, --version print the version ``` And a few environment variables override the defaults: ```bash FOXORA_ENGINE_URL engine URL (default http://127.0.0.1:4097) FOXORA_GATEWAY_URL gateway URL (default https://api.foxora.ai) FOXORA_RESOURCE_ID memory bucket id (default cli:) ``` > **See it in your terminal** `foxora --help` prints the same command list, with examples, tinted to the brand palette. Trouble running anything? Start with `foxora doctor`, then the Troubleshooting guide. --- source: https://docs.foxora.ai/api/overview title: API overview --- # API overview The Foxora gateway is a single HTTP API that routes requests to whichever model you choose. It speaks the same shape as OpenAI's chat completions endpoint, with extra Foxora-specific routes for account, usage, and models. ![API overview — screenshot placeholder](placeholder) ## Base URL ``` https://api.foxora.ai/v1 ``` Every endpoint described in these docs is relative to that base URL. We version with a leading /v1; breaking changes get a new path segment. ## Conventions - Requests and responses are JSON. Set `Content-Type: application/json`. - Authentication is via `Authorization: Bearer `. See Authentication. - All timestamps are ISO 8601 in UTC. - IDs are opaque strings — don't parse them. ## Errors Errors return a non-2xx status with a JSON body of the form: ```json { "error": { "code": "invalid_request", "message": "The 'model' field is required.", "param": "model" } } ``` ### Common status codes - 400 — malformed request body or missing fields. - 401 — missing or invalid auth token. - 402 — spend limit reached or no payment method on file. - 403 — the token is valid but not allowed to perform this action. - 404 — resource (model, agent, key) doesn't exist. - 429 — rate-limited. Back off and retry. - 5xx — gateway or upstream provider error. Retry with exponential backoff. ## Rate limits Limits are per account, not per key. Default ceilings: When you hit a limit you'll get a 429 with a Retry-After header (seconds). ## SDKs Because the chat completions surface is OpenAI-compatible, you can point the official OpenAI SDK at Foxora by overriding baseURL: ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.FOXORA_API_KEY, baseURL: "https://api.foxora.ai/v1", }); ``` ```bash pip install openai # in your code: # from openai import OpenAI # client = OpenAI(api_key=os.environ["FOXORA_API_KEY"], # base_url="https://api.foxora.ai/v1") ``` > **Migrating from OpenAI?** In most cases you only need to change two environment variables: OPENAI_API_KEY → your Foxora key, and OPENAI_BASE_URL → https://api.foxora.ai/v1. --- source: https://docs.foxora.ai/api/authentication title: Authentication --- # Authentication Foxora supports two ways to authenticate gateway requests: a Supabase JWT (used by the dashboard and desktop app) and a long-lived system API key (used by your own backends). ## Pick the right token - Supabase JWT — obtained from sign-in. Short-lived (~1 hour). Use this for browser and desktop clients that already have a user session. - System API key — created in the dashboard, prefixed with `foxora_sk_`. Long-lived. Use this for backend services and CLIs. > **Never put a system key in a browser** System keys grant full access to your account's usage and spend. Keep them server-side only. If a key leaks, rotate it immediately from the dashboard. ## Sending the token Both token types go in the same header: ```http Authorization: Bearer YOUR_TOKEN_HERE ``` ## Creating a system key - Open Dashboard → Settings. - Scroll to API keys. - Click + New key, give it a name, and copy the value once — it isn't shown again. - Store it in your secret manager or .env. ``` FOXORA_API_KEY=foxora_sk_live_abc123... ``` ## Rotating & revoking From the same settings page you can rotate (issue a new value) or revoke (delete) any key. Revoked keys stop working within seconds. ## Verifying a token To confirm a token is healthy, hit GET /v1/me. A 200 response means the token is valid and tells you which plan you're on. See /v1/me. --- source: https://docs.foxora.ai/api/chat-completions title: POST /v1/chat/completions --- # POST /v1/chat/completions The main inference endpoint. Send a list of messages, get back a model response. OpenAI-compatible — most existing SDKs work without changes. ## Endpoint ```http POST /v1/chat/completions ``` ## Request body ## Example request ```bash curl https://api.foxora.ai/v1/chat/completions \ -H "Authorization: Bearer $FOXORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [ { "role": "system", "content": "You are a concise assistant." }, { "role": "user", "content": "Summarise SOLID in one paragraph." } ], "temperature": 0.4 }' ``` ## Example response ```json { "id": "cmpl_8YqW...", "object": "chat.completion", "created": 1712345678, "model": "gpt-4o-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "SOLID is a set of five design principles..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 28, "completion_tokens": 84, "total_tokens": 112 } } ``` ## Streaming Set `stream: true` to receive server-sent events. Each event is a JSON object with a partial delta; the final event is the literal string [DONE]. ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.FOXORA_API_KEY, baseURL: "https://api.foxora.ai/v1", }); const stream = await client.chat.completions.create({ model: "gpt-4o-mini", stream: true, messages: [{ role: "user", content: "Count to five." }], }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content ?? ""); } ``` ## Tool calls Pass a list of tools and Foxora will return a `tool_calls` array when the model decides to invoke one. You execute the tool yourself and feed the result back as a `role: "tool"` message in the next call. > **Behaviour matches OpenAI** Tool-call semantics are identical to OpenAI's. Their tool-calling docs apply 1:1 — just swap the base URL. --- source: https://docs.foxora.ai/api/me title: GET /v1/me --- # GET /v1/me Returns the current user, their plan, and usage limits. Useful as a token health check and to gate features client-side. ## Endpoint ```http GET /v1/me ``` ## Example request ```bash curl https://api.foxora.ai/v1/me \ -H "Authorization: Bearer $FOXORA_API_KEY" ``` ## Example response ```json { "id": "usr_8a2f...", "email": "you@example.com", "plan": { "id": "pro", "label": "Pro", "renews_at": "2026-05-19T00:00:00Z" }, "usage": { "requests_this_month": 1842, "tokens_this_month": 942103, "spend_usd": 12.41 }, "limits": { "requests_per_minute": 300, "tokens_per_minute": 400000, "monthly_spend_cap_usd": 100 }, "features": { "cloud_agents": true, "ember_os": true, "team_workspaces": false } } ``` ## Companion endpoint For a day-by-day breakdown of activity, use GET /v1/me/usage. The dashboard's heatmap on Overview is built from this exact endpoint. ```bash curl "https://api.foxora.ai/v1/me/usage?days=30" \ -H "Authorization: Bearer $FOXORA_API_KEY" ``` --- source: https://docs.foxora.ai/api/models title: GET /v1/models --- # GET /v1/models Lists every model your account can call. The list is filtered by your plan and any provider keys configured for your account. ## Endpoint ```http GET /v1/models ``` ## Example request ```bash curl https://api.foxora.ai/v1/models \ -H "Authorization: Bearer $FOXORA_API_KEY" ``` ## Example response ```json { "object": "list", "data": [ { "id": "gpt-4o-mini", "provider": "openai", "context_window": 128000, "input_per_1k_usd": 0.00015, "output_per_1k_usd": 0.0006, "supports": ["chat", "tools", "vision", "json_mode"] }, { "id": "claude-3-5-sonnet", "provider": "anthropic", "context_window": 200000, "input_per_1k_usd": 0.003, "output_per_1k_usd": 0.015, "supports": ["chat", "tools", "vision"] } ] } ``` ## Notes - Pricing is per 1,000 tokens, billed in USD. Foxora applies the provider's public pricing without markup unless your plan says otherwise. - The `supports` array tells you which features the model can use — e.g. tool calling or vision. Use this to gate UI client-side. - New models appear here automatically when added to the gateway. --- source: https://docs.foxora.ai/extensions/overview title: Extensions overview --- # Extensions overview Extensions are how you add new tools, integrations, and surfaces to Foxora. Some are built by the Foxora team, some by the community, all live in the same hub. ![Extensions overview — screenshot placeholder](placeholder) ## What an extension can do - Add tools — expose a new capability (e.g. send email, query a Postgres database) that any agent can call. - Add integrations — connect Foxora to a third-party service (e.g. Slack, Notion, GitHub). - Add UI — ship a panel that appears in Foxora Desktop when its extension is installed. - Add triggers — new ways to start agents (e.g. on a Slack message). ## Where to find them Open Dashboard → Extensions for the full hub. Each extension shows what it does, who built it, and which permissions it needs. > **Old route names** The hub used to live at /dashboard/plugins, /dashboard/integrations, and /dashboard/bugbot. Those URLs now redirect to the unified Extensions page. ## Permissions Every extension declares the permissions it needs (network, file system, external API access). You see the full list before install and can revoke any of them later. ## Pricing Foxora-built extensions are free with any plan. Third-party extensions can be free or paid — paid ones bill through your existing Foxora payment method, no extra setup. ## Where to next - Build your own extension - Browse the hub --- source: https://docs.foxora.ai/extensions/building-extensions title: Building extensions --- # Building extensions A walkthrough of how a Foxora extension is structured, how to develop one locally, and how to publish it to the hub. > **Public SDK in beta** The extension SDK is in private beta. The shape below is stable for the beta program but may evolve before public release. Email builders@foxora.ai to request access. ## Anatomy of an extension An extension is a folder with three files at minimum: ``` my-extension/ ├─ manifest.json # name, version, permissions, exports ├─ index.js # tool / trigger handlers └─ README.md # description shown in the hub ``` ## manifest.json ```json { "name": "weather", "version": "0.1.0", "description": "Look up the weather for a city.", "author": "your-handle", "permissions": ["network"], "tools": [ { "id": "weather.lookup", "label": "Look up weather", "input_schema": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] } } ] } ``` ## index.js Each tool the manifest declares maps to a handler exported from index.js. Handlers are async and receive the validated input plus a small ctx object. ```js export const tools = { "weather.lookup": async ({ city }, ctx) => { const res = await ctx.fetch( `https://api.weather.example.com/v1/now?q=${encodeURIComponent(city)}` ); const data = await res.json(); return { temp_c: data.temp, summary: data.summary }; }, }; ``` ## Run it locally - Install the CLI: `npm i -g @foxora/extensions-cli` (beta) - From your extension folder: `foxora-ext dev` - Foxora Desktop picks up the local extension automatically and shows it under Extensions → Local. - Trigger the tool from a chat or with `foxora-ext invoke weather.lookup --input city=Berlin`. ## Publishing - Bump the version in manifest.json. - Run `foxora-ext publish`. - The CLI uploads the bundle and opens a review request in the hub. - Foxora reviews for safety + permissions and publishes within a few business days. > **Keep the surface small** The best extensions expose one or two well-named tools that do exactly one thing each. Agents are much better at picking the right tool when there are fewer of them. --- source: https://docs.foxora.ai/billing/plans title: Plans & pricing --- # Plans & pricing Foxora has three plans — Free, Pro, and Team. Plans gate features and set monthly rate limits. Spend itself is metered separately. ## Plan summary ## How spending works Plans cover the platform — not the model spend. Every gateway request is metered at the provider’s public token price (see /v1/models for live pricing) and rolled into your monthly invoice. - Free plans get $1 of model credit per month and stop there. - Pro and Team plans add a metered line item to the monthly invoice. - You can set a hard monthly spend cap from Dashboard → Billing. > **Hard cap recommended** A spend cap pauses gateway requests once you hit your limit, so a runaway agent can never surprise you with a bill. We strongly recommend setting one. ## Upgrading - Open Dashboard → Billing. - Click Upgrade next to the plan you want. - Enter card details — we use Stripe Checkout, no card data hits Foxora servers. - Your plan flips immediately and pro-rates the current month. ## Downgrading or cancelling Same place — Billing → Change plan. Downgrades and cancellations take effect at the end of the current billing period; you keep the higher plan until then. ## Refunds We refund unused full months on request within 14 days. Partial-month usage and metered model spend aren’t refundable. Email billing@foxora.ai. --- source: https://docs.foxora.ai/billing/usage title: Usage & spending --- # Usage & spending Every gateway call counts towards two things — your plan's rate limits and your metered spend. Here's how to see and control both. ## Where to see it | Location | What it shows | | --- | --- | | Dashboard → Overview | Six-month activity heatmap. | | Dashboard → Usage | Per-day breakdown of requests and tokens. | | Dashboard → Spending | Per-day USD breakdown grouped by model. | | Dashboard → Billing | Invoices and payment methods. | ## What gets metered ### Tokens Every chat completion is billed by token, split into input (the prompt) and output (the completion). Pricing per 1,000 tokens depends on the model — see `/v1/models`. ### Requests Each HTTP call counts as one request, regardless of token volume. Requests are what your plan’s rate limits gate. ### Cloud agent runs Cloud agent runs charge for the model tokens they consume plus a small per-run platform fee (currently $0.001 per run on paid plans, free on Free). ## Pulling usage programmatically ```bash curl "https://api.foxora.ai/v1/me/usage?days=30" \ -H "Authorization: Bearer $FOXORA_API_KEY" ``` Returns an array of day buckets with request count, input/output tokens, and USD spend. The dashboard heatmap and graphs are built from this exact endpoint. ## Spend caps Set a monthly USD ceiling in Billing → Spend cap. When you hit it, gateway requests start returning 402 until the next billing cycle (or until you raise the cap). Requests that would push you past the cap are rejected before they leave the gateway, so you’re never charged for them. > **Free plans always have a cap** Free accounts have a built-in $1 monthly model-credit cap that can’t be raised. To go higher, upgrade to Pro. ## Invoices Invoices arrive on the first of each month for the previous month’s usage. They’re downloadable as PDF from Billing → Invoices and emailed to your account address. --- source: https://docs.foxora.ai/support/troubleshooting title: Troubleshooting --- # Troubleshooting Foxora is built to recover on its own — the engine runs as a supervised process the app restarts if it dies, and the runtime link self-repairs. When something still won't budge, these are the fixes, in the order worth trying them. > **Start with the connection probes** Most issues are a connection that didn’t come up. Open Settings (⌘, / Ctrl+,) → Advanced — it shows a live status dot for the Engine, Login, and Gateway. On the CLI, `foxora doctor` checks the same things. Whatever reads Unreachable is your starting point. See the Settings reference. ## The app is stuck on “Starting Foxora” On launch the app spawns the engine daemon and polls it until `/health` answers on `127.0.0.1:4097`. If it sits on “Starting Foxora”, the engine either hasn’t come up or a previous instance is still holding the port. ### What to try - Give it a moment. First launch (and the first launch after an update) provisions the runtime, which can take a minute on a slow connection. - Quit fully and reopen. Make sure the app is completely closed first — an orphaned engine can keep the port busy and stall the new one. - Check the port. A stray process on :4097 shadows a fresh engine. Find and stop it, then relaunch: ```bash # who's on the engine port? lsof -i :4097 # stop it by PID, then reopen Foxora kill ``` > **The engine is supervised** You don’t normally manage the engine yourself — the app owns its lifecycle and restarts it automatically if it exits. If it never reaches ready at all, the issue is usually the runtime (next section) rather than the engine process. ## Engine unreachable If chat shows “couldn’t reach the engine” or Settings → Advanced marks the Engine row Unreachable, requests aren’t getting through to :4097. ### What to try - Re-check after a few seconds. The probe re-runs; a transient restart clears on its own. - Confirm your network. The Gateway row needs an internet connection — a blocked or offline network shows it Unreachable even when the local engine is fine. - Make sure you’re signed in. A signed-out app can’t reach the gateway. Sign in again from Settings → Account (or `foxora login`). - From the CLI, run the one-shot diagnostic: ```bash foxora doctor # checks: platform · runtime · engine · account · gateway ``` ## Stale or broken runtime The engine and its bundled bun live in `~/.foxora/runtime/current`. The app expects to find engine.js and bun there. If that link is missing or points at a half-installed version, the engine won’t start — `foxora doctor` reports the runtime as not installed. Foxora self-heals where it can: when current is missing it relinks to the newest good versioned runtime it finds. When it can’t, re-provision: ```bash # re-provision the runtime (engine · memory · workspace · bun) foxora setup # update the CLI and refresh the runtime to the latest foxora update ``` > **Force a clean reinstall** If a runtime is genuinely corrupt, you can force a fresh provision by setting `FOXORA_SETUP_FORCE` before `foxora setup`. This replaces `~/.foxora/runtime/current` — your sessions and memory live elsewhere in the data folder and are untouched. **macOS / Linux** ```bash FOXORA_SETUP_FORCE=1 foxora setup ``` ## Where logs & the data folder live Everything Foxora keeps on this device — the runtime, Memory Den, sessions, and workspace files — lives in one predictable data home: ``` ~/.foxora ``` It’s a hidden dot-folder by convention (like ~/.docker). The fastest way to open it is Settings → Advanced → Foxora data folder → Reveal, which opens it in Finder / Explorer. ### Crash log If the app shell itself faults, it writes a crash log to your system temp directory so the fault is never silent: ``` # in your temp dir, e.g. $TMPDIR/foxora-crash.log /tmp/foxora-crash.log ``` > **Sharing diagnostics** When reporting an issue, the output of `foxora doctor` plus the data folder path tells us almost everything we need — platform, runtime version, engine state, and whether the gateway is reachable. ## Resetting local preferences If the UI looks wrong — a broken theme, accent, or font — you can reset just the on-device preferences without touching your account or sessions. Open Settings → Advanced → Reset local preferences, then confirm. It clears theme, scheme, accent, and font and reloads. > **What reset does and doesn't touch** Resetting preferences only clears appearance settings stored on this device. Your account and sessions are untouched. It does not reinstall the runtime — for that, use `foxora setup` (above). ## Still stuck? Work through it in this order, and you’ll have caught the vast majority of problems: - Check Settings → Advanced probes (or `foxora doctor`). - Quit fully and reopen; free up :4097 if it’s held. - Re-provision the runtime with `foxora setup`. - Reveal the data folder and grab the crash log if the app faulted. - Reset local preferences if only the UI looks wrong. Need a fresh install instead? See Installing Foxora, or the Settings reference for every toggle in one place.