Troubleshooting

Desktop App

App won't open on macOS

Right-click the app in Applications and select Open. macOS Gatekeeper may block first launch. Foxl is notarized by Apple (Team ID: B47A25FR9P).

"Server runtime not found" / "Node.js not found"

Foxl bundles its own server runtime - Bun on macOS and Linux, Node.js on Windows - and does not need a system install of either. If you see this error, the app bundle may be corrupted. Try re-downloading and reinstalling from foxl.ai.

Agent not responding

1. Check Settings > Logs for errors
2. Try restarting the desktop app
3. If you connected a cloud provider, verify your internet connection
4. Check that your API key is still valid in Settings > Model & provider

High memory usage

The agent runs as a separate server process. If memory usage is high:

1. Close unused conversations
2. Restart the app to clear agent state
3. Check for long-running background processes on the Agents page

Linux: the AppImage does not start

Two separate failures, and neither is a security dialog:

1. Permission denied - a browser download has no execute bit. Run chmod +x Foxl-latest.AppImage.
2. dlopen(): error loading libfuse.so.2 / "AppImages require FUSE to run" - Ubuntu 22.04 and later ship fuse3 only. Install libfuse2 (sudo apt install libfuse2t64 on 24.04). No --no-sandbox flag is needed.

The app shows an error dialog at launch naming tunnel-sessions.js

The first build of v0.6.27 shipped without one file the tunnel needs and stopped at launch on every platform. An app that cannot start also cannot update itself, so download it again from foxl.ai and reinstall.

Stuck on the loading screen after an update

With Keep running when closed on, an update could leave the background service unregistered while the app waited for it. Fixed in v0.6.21: every launch repairs a missing service, and if it truly cannot start, Foxl runs the server itself and says so in Settings. If you still see the "Agent server stopped" card, its Restart server button reinstalls the service. The server diagnostics under Settings > Diagnostics name the runtime the server is on and say whether the service is registered.

Background service stops right after you move or reinstall the app

The service file records the installed app's path. If the app moves, the daemon exits (status 78) rather than looping. Open the installed Foxl once - every launch rewrites the service file - and it comes back.

A long chat forgot everything mid-turn

Before v0.6.21 a conversation that hit the model's context limit could be dropped entirely and answered as if it were new. It is now compressed at 70% of the window, and each compaction is written to Settings > Logs with the message count before and after.

Foxl is stuck in the wrong language

Opening Foxl Code used to freeze the language to whatever was detected at that moment. v0.6.25 clears a language nothing recorded you choosing; if yours is still wrong, open Settings > General and choose Auto detect once. On iPhone and iPad the language also has its own row in the iOS Settings app.

Web App (app.foxl.ai)

Can't sign in

• Try a different sign-in method (Google, Apple, GitHub, an email magic link, or a password if you set one)
• Clear browser cookies for app.foxl.ai and try again
• Check that your browser allows third-party cookies (needed for OAuth)

"Desktop Offline" but desktop app is running

1. Check that both devices are connected to the internet
2. Verify the connection under Settings > Connect > Mobile/Web on the desktop
3. Toggle Remote Access off and on there - there is no pairing code to re-enter, the two find each other by account
4. Check if a firewall or VPN is blocking WebSocket connections

Conversations not loading

On app.foxl.ai and the phone, your conversations are the ones on your desktop - there is no cloud copy, because foxl.ai serves no models and keeps no chats. If the list is empty or stale:

• Check the connection dot: Desktop Offline means the desktop is asleep, quit, or unreachable (see above)
• Turn on Keep running when closed so a quit does not take your conversations offline
• Foxl Code conversations and tasks are the exception - they live on Foxl's servers and load without the desktop

Slow responses

• Check your internet connection
• Try a faster model from your provider, or turn thinking off for simple questions
• Ask in Discord if responses are slow for everyone, not just you

Chrome Extension

Extension shows "Disconnected"

The extension connects to the desktop agent via localhost WebSocket:

1. Make sure the desktop app is running
2. Check chrome://extensions for any error messages
3. Reload the extension (toggle off/on in chrome://extensions)

The extension now says which of these it is rather than showing a bare grey dot: the desktop app is required (with a link to it, and the custom-port setting) if it has never seen a desktop, or reconnecting if it has. It also stops promising an automatic reconnect once a month has passed with no desktop answering.

The two also exchange versions, so an extension that has auto-updated past your desktop app says so instead of half-working. If you see that, update the desktop app.

Agent can't see page content

Some pages block content extraction:

• Pages with strict CSP (Content Security Policy)
• CAPTCHAs and bot protection
• Dynamic SPAs that load content after initial render

Try refreshing the page or using the Playwright-based browser tool as a fallback.

Extension interfering with normal browsing

The extension is passive by default - it only activates when the agent requests it. If you experience issues:

1. Disable the extension in chrome://extensions
2. Use only when needed with the desktop agent

Windows: SmartScreen warning on first launch

Foxl for Windows is signed with a self-signed certificate, so on a fresh download SmartScreen shows "Windows protected your PC" with Don't run as the only button and the publisher as Unknown publisher. Click More info, then Run anyway. The warning does not fade with time or downloads - only a trusted certificate would remove it - and Microsoft Defender itself does not flag the file. Edge or Chrome may also hold the download; choose Keep there first.

Windows: "Node.js not found" error

Foxl for Windows bundles its own Node.js runtime and does not require a system Node.js installation. If you see this error, try re-downloading and reinstalling from foxl.ai.

Windows: PowerShell terminal not working

Foxl prefers PowerShell 7+ (pwsh.exe). If not available, it falls back to Windows PowerShell. Install PowerShell 7:

winget install Microsoft.PowerShell

Models and cost

"foxl.ai is not serving model inference right now"

Working as intended. Foxl is free and does not serve models, so you supply the model: your own provider key, a local model, or a Claude / ChatGPT subscription you already pay for. Set one up in Settings > Model & provider, and see Cost & model access.

The model picker says "No provider connected yet"

Same cause. Foxl's own catalog is empty, so the models you can pick are the ones your provider gives you. Press Open Model & provider in the picker, connect one, and the list fills in with that provider's own catalogue. On the phone or the web the models come from your Foxl desktop, so open Foxl on your computer to choose one.

"Rate limit exceeded" or a 429

That is your provider's limit, not Foxl's - the relay refuses model requests outright rather than rate-limiting them. Wait for the vendor's window, or pick another model. On OpenRouter a free key has a daily cap on free models, and Automatic fallback (Settings > Model & provider) can hand the turn to another model you have set up.

"This request requires more credits, or fewer max_tokens"

OpenRouter reserves the whole reply length against your balance before it answers. In Settings > Model & provider, lower Maximum reply length for that provider, switch on Only free models, or add credit with the vendor. Foxl already asks for no more than the model allows.

Credits show as 0

Foxl is free and there is nothing to buy, and a model turn never spends credits. A zero balance matters in two places: a Foxl Code task or terminal on Remote is refused with "credits exhausted" until your next monthly refill (work on This computer is unaffected), and the Notes Foxl Relay transcription engine, on the accounts Foxl has enabled for it, stops. If a balance looks wrong, refresh, or sign out and back in to re-sync.

Chat answers a bare HTTP 500 on OpenRouter or another compatible vendor

Fixed in v0.6.27 for all of them (DeepSeek, Groq, Z.ai, Kimi, Qwen, Together, Mistral, Fireworks, Perplexity, xAI, Cerebras, SambaNova, AI21, Hugging Face, MiniMax, vLLM, LM Studio). Update; the same release also stops a second, unusable "OpenAI" section appearing in the picker when you add another vendor's key.

Notes

A recording ran to the end with an empty transcript

Before v0.6.26, recording on a phone or the web with your own AWS account streamed audio that Amazon then refused to transcribe - it looked like a dead microphone. Update the app. Since v0.6.28 a session the provider rejects (a lapsed AWS login, a drained ElevenLabs key) stops the recording and shows the provider's own message instead; a recording stopped that way does not keep its audio yet.

The "Foxl Relay" transcription engine is missing, or Settings asks you to pick another

That engine streams to Amazon on Foxl's own account and is offered only to accounts Foxl has enabled for it. Pick Amazon Transcribe with your own AWS account (the default - your desktop signs the connection), On device on an Apple Silicon Mac, or your own Deepgram, AssemblyAI, OpenAI or ElevenLabs key pasted into the desktop.

"On device" is greyed out

It runs the speech engine on an Apple Silicon Mac only; the row says so on other machines, and it is not offered on the phone or the web.

Notes AI says "OpenAI API key not configured" on OpenRouter, DeepSeek, Groq or another vendor

Fixed in v0.6.24 - summaries, titles, reports and translation now run on the model you selected in the desktop's Model & provider. If you also had an OpenAI key saved, the old bug sent that vendor's model name to OpenAI under your key, which is what an unexpected OpenAI 401 or charge from that period was.

Foxl Code

Settings shows no Code panes

Your account is on the Foxl Code waitlist; the whole Code group is hidden until access is granted, and Foxl Code itself says where you stand: open it and the waitlist screen says you will be notified when access is granted. Questions about access go to support@foxl.ai.

A cloud terminal says "This session went to sleep"

A Remote machine is recycled after about fifteen idle minutes. Press Reconnect in the pane or on the Runtimes screen; it resumes on the same saved workspace. A pane that reported this wrongly clears itself once the agent answers.

Typing into a cloud terminal while it starts

A Remote machine takes about thirty seconds to come up (Codex about six). Keys typed in that window are held on the server and delivered in order once the agent is ready - they survive closing the pane or reloading. A Kiro pane then spends a while on Initializing: that is Kiro starting the MCP servers you configured, and you can type during it.

Signed out of the whole app after a Foxl Code request

A Foxl Code request answered with a 401 clears the session everywhere in the app - the Code client has no token refresh of its own. Sign in again; if it recurs while other screens were fine, report it with the time it happened.

Phone apps

Android: recording or the mic button is refused

Fixed in v0.6.23 - the app never asked for the permission, so the system dialog never appeared. Update the app.

Scheduling

Schedules not running

1. The desktop app must be running for schedules to execute - or turn on Keep running when closed so a quit does not pause them
2. Check the Schedules page for any failed runs
3. Verify the cron expression is correct
4. Check Settings > Logs for errors during execution

Schedule ran but produced no output

• The scheduled task may have failed silently
• Check Settings > Logs for the specific schedule execution
• Try running the task manually first to verify it works

Getting Help

Report an issue, from the app

Settings > General > Report an issue copies the build you are running, your platform and your language, then opens the Foxl Discord so you can paste them with what went wrong. Reports used to arrive without that line, which costs a round trip before anyone can start looking.

It is findable from the command palette by typing "report" in any of the ten languages.

Elsewhere

• Discord: Join our community - use /ask for instant AI answers, or create a private support ticket
• Email: support@foxl.ai for billing and account issues
• GitHub: Report bugs for the desktop app