> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whim.run/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ & Troubleshooting

> Answers to common questions and solutions to common issues.

## Frequently Asked Questions

### General

<AccordionGroup>
  <Accordion title="What is Whim?">
    Whim is a cloud dev workspace for running AI coding agents. Each task runs in its own isolated container with a full dev environment, terminal sharing, and git branch isolation. Write a prompt, pick a model, and watch it code in real time.
  </Accordion>

  <Accordion title="How is Whim different from running Claude Code locally?">
    Whim handles all infrastructure — cloud containers, git branch management, environment setup, and multi-agent orchestration. Run multiple tasks in parallel without local resources, collaborate with teammates in real time, and switch between AI providers seamlessly.
  </Accordion>

  <Accordion title="Which browsers are supported?">
    All modern browsers: Chrome, Firefox, Safari, and Edge. For the best experience, use a Chromium-based browser.
  </Accordion>
</AccordionGroup>

### Tasks

<AccordionGroup>
  <Accordion title="How many tasks can I run in parallel?">
    Free and Pro: **20 active tasks** per team. Max: **40+**, scaling with your capacity multiplier.
  </Accordion>

  <Accordion title="What happens when a task fails?">
    Whim detects container failures (typically within 30 seconds) and marks the task as stopped. Review terminal output to diagnose, then fork or re-run with an updated prompt.
  </Accordion>

  <Accordion title="Can I interact with a running task?">
    Yes. Type in the live terminal to respond to prompts, run commands, or guide the agent. You can also send follow-up prompts.
  </Accordion>

  <Accordion title="What's the difference between a task and a todo?">
    A **task** launches immediately with an AI agent. A **todo** is planned work in your backlog until you launch it.
  </Accordion>
</AccordionGroup>

### Files & Attachments

<AccordionGroup>
  <Accordion title="How do I upload files?">
    Three ways:

    * **Drag and drop** files onto the task composer or active task
    * **File picker** — click the attachment button
    * **Paste images** from your clipboard into the composer

    Limits: 25 MB per file, 10 files per task. Supported types include images (PNG, JPG, GIF, WebP, SVG), documents (PDF, TXT, MD), code files, config files, and data files (CSV, TSV). Executables and binaries are blocked.
  </Accordion>

  <Accordion title="How do files reach the AI agent?">
    Attached files are injected into the container via the `WHIM_ATTACHMENTS` environment variable with sanitized filenames and signed download URLs (valid 1 hour). The runtime downloads them automatically.
  </Accordion>

  <Accordion title="Can I preview files in the browser?">
    Yes. Images show as inline thumbnails. Click any attachment to open a full-screen preview with zoom support (images), syntax highlighting (code), or native rendering (PDFs). Previews use signed URLs scoped to your session.
  </Accordion>
</AccordionGroup>

### Notifications

<AccordionGroup>
  <Accordion title="How do I set up notifications?">
    Go to **Settings → Notifications**, click **Enable Notifications** to trigger your browser's permission prompt, then toggle individual types:

    * **Claude waiting for input** — agent finished, awaiting response
    * **Comments on my tasks** — someone commented on your task
    * **When I'm @mentioned** — someone mentioned you
    * **Reactions to my comments** — someone reacted to your comment

    Notifications only appear when the Whim tab is not in focus.
  </Accordion>

  <Accordion title="I accidentally denied notification permission — how do I fix it?">
    Reset in your browser's site settings:

    * **Chrome**: Lock icon → Site settings → Notifications → Allow
    * **Firefox**: Lock icon → Clear notification permission
    * **Safari**: Safari → Settings → Websites → Notifications → find whim.run → Allow
  </Accordion>
</AccordionGroup>

### Authentication

<AccordionGroup>
  <Accordion title="How does authentication work?">
    Whim uses **GitHub OAuth**. Sign in with your GitHub account — your profile is created automatically from your GitHub email and avatar. Sessions persist across tabs and refreshes with transparent token refresh.
  </Accordion>

  <Accordion title="What is demo mode?">
    Demo mode lets you explore Whim without a GitHub account using anonymous auth. Functionality is limited. Upgrade to a full account by signing in with GitHub at any time.
  </Accordion>

  <Accordion title="How do I sign out?">
    Open the user menu (your avatar in the sidebar) → **Sign out**. This ends your session across all tabs and devices.
  </Accordion>
</AccordionGroup>

### Data & Privacy

<AccordionGroup>
  <Accordion title="How is my data handled?">
    * **Container isolation** — each task runs in its own isolated container on Fly.io with a separate filesystem and network stack. Destroyed when the task ends.
    * **Workspace isolation** — Row-Level Security (RLS) ensures you can only access data in workspaces you belong to.
    * **AI providers** — your code and prompts are sent to the provider you select. Today that means Anthropic or OpenAI; OpenRouter support is coming soon. Each provider has its own data policy. Whim sends only the minimum context necessary.
  </Accordion>

  <Accordion title="Does Whim store my code?">
    Your code lives in your GitHub repository. Whim clones it into an ephemeral container per task and destroys the container when done. File attachments are stored in Supabase Storage, scoped to your workspace.
  </Accordion>

  <Accordion title="Can I request data deletion?">
    Yes. Request access to or deletion of your personal data at [whim.run/data-request](https://whim.run/data-request). See also: [Terms of Service](https://www.whim.run/terms), [Privacy Policy](https://www.whim.run/privacy), [Cookie Policy](https://www.whim.run/cookies).
  </Accordion>
</AccordionGroup>

### Billing

<AccordionGroup>
  <Accordion title="How are CUs calculated?">
    CUs combine **container runtime** (1 CU ≈ 30 min) and, when token-billed providers are enabled, **AI token usage** (\~14,000 input tokens per CU). See [Plans, Pricing & Usage](/billing/plans-pricing-and-usage#compute-units-cus) for full details.
  </Accordion>

  <Accordion title="Is there a free tier?">
    Yes. The Free plan gives you **25 CU per week** at no cost. During alpha, all plans include a promotional CU boost, and your effective allocation is shown in **Settings → Usage**.
  </Accordion>

  <Accordion title="What happens when I run out of CUs?">
    A grace period lets running tasks finish briefly. You can't start new tasks until your weekly period resets or you upgrade.
  </Accordion>
</AccordionGroup>

### AI Providers

<AccordionGroup>
  <Accordion title="Which models are supported?">
    Models from **Anthropic** (Claude) and **OpenAI** (Codex). Additional models via **OpenRouter** are coming soon.
  </Accordion>

  <Accordion title="Can I use my own API keys?">
    Claude and Codex use your own subscription — Whim charges CUs for container time only. Built-in API access via OpenRouter is coming soon.
  </Accordion>

  <Accordion title="Can I switch models mid-task?">
    Models are selected at task creation. To try a different model, fork the task or create a new one.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

### Task Issues

<AccordionGroup>
  <Accordion title="Task stuck on 'Setting up environment'">
    Containers usually start within 60 seconds (up to 3 minutes for custom images). If stuck:

    1. **Check CU balance** — can't start tasks when depleted
    2. **Check active task limit** — Free/Pro allow 20; archive or complete old tasks
    3. **Try again** — transient infra issues occasionally delay creation
    4. If persistent, check the [Whim status page](https://www.whim.run) or contact support
  </Accordion>

  <Accordion title="Task fails immediately after starting">
    Usually a workspace image or environment issue:

    * Check image build logs in **Settings → Workspace Images**
    * Ensure your image includes required dependencies
    * Verify GitHub App has access to the repository
  </Accordion>
</AccordionGroup>

### Terminal Issues

<AccordionGroup>
  <Accordion title="Terminal not loading">
    1. Refresh the page to re-establish the connection
    2. Check your internet connection (requires stable WebSocket)
    3. Try a different browser — some extensions interfere with WebSockets
    4. Disable VPN if applicable
  </Accordion>

  <Accordion title="Terminal disconnecting frequently">
    Brief disconnections when switching tabs (especially Safari) are normal — Whim auto-reconnects. For persistent disconnections: check network stability, disable tab sleeping in browser settings, try a wired connection.
  </Accordion>
</AccordionGroup>

### Git Issues

<AccordionGroup>
  <Accordion title="Git push or pull fails">
    1. Verify GitHub App installation is active in **Settings → GitHub**
    2. Ensure the app has access to the specific repository
    3. If you recently changed permissions on GitHub, reconnect the integration
    4. The installation token may have expired — try removing and re-adding the integration
  </Accordion>

  <Accordion title="Branch conflicts">
    Each task uses its own branch. If conflicts occur when pushing:

    * The base branch may have updated since the task started
    * Fork the task to retry with a fresh branch
    * Use the terminal to manually resolve conflicts
  </Accordion>
</AccordionGroup>

### AI Provider Issues

<AccordionGroup>
  <Accordion title="Provider connection errors">
    * Check the provider's status page (Anthropic or OpenAI today; OpenRouter will apply once CCR launches)
    * Try a different model by creating a new task
    * Verify CU balance — some errors occur when balance is too low
  </Accordion>

  <Accordion title="Agent seems stuck or unresponsive">
    * Send a follow-up prompt to guide the agent
    * Check the terminal — the agent may be waiting for input
    * Fork the task with a more specific prompt
    * Whim detects idle agents (over 2 minutes) and can alert you via notifications
  </Accordion>
</AccordionGroup>

### CU Balance Issues

<AccordionGroup>
  <Accordion title="CU balance seems wrong">
    Check **Settings → Usage** for per-task breakdown. Remember:

    * CUs combine container runtime **and** token usage — high-token tasks may cost more than expected
    * Reserved machines consume 3 CU/week each
    * Periods reset weekly from your subscription anchor, not on a fixed day
  </Accordion>

  <Accordion title="Can't start tasks despite having CU balance">
    You've likely hit your **active task limit** (20 for Free/Pro, 40+ for Max). Complete or archive finished tasks.
  </Accordion>
</AccordionGroup>

### Browser Notifications

<AccordionGroup>
  <Accordion title="Not receiving notifications">
    1. Check **Settings → Notifications** — master toggle and relevant types must be on
    2. Check browser permissions for whim.run
    3. Notifications only fire when the Whim tab is **not in focus**
    4. On macOS, ensure notifications are enabled for your browser in **System Settings → Notifications**
  </Accordion>
</AccordionGroup>

### Mobile

<AccordionGroup>
  <Accordion title="Limited functionality on mobile">
    Whim is optimized for desktop. On mobile: the terminal is harder to use on small screens, drag-and-drop isn't available (use the file picker), and browser notifications may behave differently by OS.
  </Accordion>
</AccordionGroup>