Skip to main content

FAQ

Version: 2.24 | Last updated: 2026-08-31

Answers to the most common questions about Bluebox. For setup instructions, see Getting Started.

Getting started​

Do I need to write any agent code?​

No. Bluebox is a SaaS product. You install the CLI, connect your GitHub account and observability platform through the web UI, and Bluebox handles the rest. No ML configuration, no custom pipelines.

Which coding agents does Bluebox support?​

bluebox setup detects installed coding agents and installs Bluebox skills into them automatically. Claude Code and Kiro are fully supported; Cursor, GitHub Copilot, and OpenCode are experimental. For any other agent, you can install skills manually. See Installing skills into other agents.

What operating systems does the CLI support?​

macOS, Linux, and Windows. See Getting Started for install commands.

Is Bluebox available in my region?​

Bluebox is not open for new sign-ups in some countries because of legal and compliance restrictions. If sign-up tells you Bluebox is not available in your region, it cannot be used from your current location. This check applies only to new sign-ups; it does not affect existing accounts.

Can I use Bluebox without an observability platform?​

You can connect GitHub and run investigations, but the diagnosis quality is significantly better with live telemetry. Bluebox generates OpenTelemetry instrumentation guidance during setup to help you get there.

Can I use multiple GitHub repositories?​

No. Currently you can connect one repository per workspace.

How do I share feedback about Bluebox?​

Open your profile menu in the sidebar and select Give feedback. Rate your experience from one to five stars and, optionally, add a comment. If you rate three stars or fewer, a follow-up prompt asks how Bluebox could improve. Your rating and comments go straight to the team. There is nothing else to set up.

Will I be signed out if I leave Bluebox open without using it?​

Yes, after a period of inactivity. Bluebox warns you before signing you out, with the option to stay signed in. Actively using the browser tab (clicking, typing, or scrolling) keeps your session alive; leaving the tab open in the background does not.

Investigations​

How long does an investigation take?​

Most investigations complete in two to ten minutes depending on the complexity of the incident and the breadth of telemetry available.

What happens when an investigation finishes?​

Bluebox produces an evidence-backed root-cause report (root cause, evidence, and a recommended fix) that you can act on yourself or hand to your coding agent. It also files a GitHub issue for actionable findings, following the workspace's GitHub issue policy: smart (the default) files for code-fix and manual-intervention outcomes and skips inconclusive runs and repeat firings of an already-open problem; always files every time; never files none. Workspace owners change the policy under Settings → Investigations; other members see the current value.

Can Bluebox change my code without my review?​

No. Bluebox proposes fixes; it never merges changes or pushes to your branches. Every code change requires your explicit review and approval. See Security and Privacy for the full list of boundaries.

What's the difference between Chat and Investigations?​

Chat is conversational: good for quick questions, exploring hypotheses, and follow-ups. Investigations produce structured output: a full analysis with evidence for every claim, delivered as a GitHub issue. Use Chat to explore; use Investigations when you need a structured result.

Are chat conversations saved?​

Yes. Conversations are saved server-side and persist across browser sessions. They do not expire automatically.

Why did Bluebox reply with an apology instead of an answer in chat?​

Occasionally the agent gets stuck retrying the same step without making progress. When that happens in a chat conversation, Bluebox now replies with a plain message asking you to rephrase or add more detail, instead of the conversation just failing with no reply. Rephrasing the question or narrowing the scope usually gets past it.

Why does a task or investigation show "Limit reached" instead of finishing?​

Your workspace has a daily AI usage limit. If a running task or investigation hits that limit before it finishes, Bluebox stops it and marks it Limit reached instead of letting it fail silently. The task page shows when your usage resets and a Start again button. Click it once your usage has reset to start the same work over from scratch. Starting a brand-new task or investigation while your usage limit is active is blocked the same way, with an explanation and a countdown to when you can try again.

Data and security​

What data does Bluebox read from my repositories?​

Bluebox reads code, commits, pull requests, and issues for investigation context. It does not read secrets, environment variables, or credentials stored in your repository.

How do I know what data bluebox ask used to answer?​

Every bluebox ask answer ends with an Evidence section listing the production data it actually queried, plus any gaps, like a query that came back empty or failed. It reflects what the agent's tool calls returned, not a summary the model writes about itself, and it's metadata only: service names, data types, and time windows, never raw log or query content. See the CLI Reference for details.

Who can see my workspace data?​

Only members of your workspace. See Security and Privacy for the full picture.

Troubleshooting​

My GitHub OAuth keeps failing​

Check that your browser is not blocking pop-ups or third-party cookies. Try a private/incognito window with extensions disabled.

The CLI says my token expired​

CLI sign-in tokens expire after 14 days of inactivity. Run bluebox auth login to re-authenticate.

The CLI says my saved sign-in cannot be used​

Your sign-in is stored for one Bluebox server address and kept in your operating system's keychain. It stops working when either half no longer matches: you point the CLI at a different address than the one you signed in to, or the keychain entry is gone because you moved to a new machine or the system cleared it.

Sign in again:

bluebox auth login

This is not a connection problem, so retrying the command will not clear it.

I'm not seeing my GitHub repositories in Setup​

Confirm the Bluebox GitHub App is installed on the correct account or organization. The Setup picker shows an install prompt if the app is missing, and suggests reinstalling the app if Bluebox can no longer use the installation it has. If Setup instead says your selected repository is no longer accessible, the app is still installed but that repository can no longer be reached, so pick another repository on the Setup page.

Returning to Setup later does not require you to sign in to GitHub again: Bluebox reads your repositories through the installed app. If your GitHub sign-in has genuinely expired, Setup says so and takes you back to GitHub, returning you to the same step afterwards.

A repository is degraded — "Action needed" or "Repositories need attention"​

Bluebox flags a repository this way when it can no longer reach it — usually because the GitHub App was removed from the account or organization that owns the repository, the repository was dropped from the App's selected repositories, or it was deleted on GitHub. The repository stays listed rather than disappearing, so you can see what changed and decide what to do. If your workspace tracks more than one repository, the Overview page summarizes this with a Repositories need attention chip; select it to see which repositories are affected and to open Setup.

You have two ways to clear the flag. If the repository still exists on GitHub, restore access to it — reinstall the Bluebox GitHub App on that account or organization, and add the repository back to the App's selected repositories if it was removed from that set; the repository returns to normal on the next check. If the repository was deleted on GitHub, it cannot be restored — uncheck it on the Setup page to remove it. Unchecking is also how you remove any repository you no longer want Bluebox to track.

Overview says findings are unavailable​

Bluebox reads findings from your observability platform each time Overview loads. When that read does not succeed, Overview tells you so rather than showing a loading indicator that never finishes.

If the message lists one or more permissions, the token you connected cannot read the data Bluebox needs. Grant the listed permissions on that token in your observability platform, then open Setup and re-save the connection. A connection can pass its first check and still be missing permissions, because Bluebox saves the connection as soon as it can read at least one kind of data.

If no permission is listed, the read did not finish in time. This is usually temporary, and most common on large environments. Select Retry. If it keeps happening, share feedback so we can look into it.

Overview refreshes findings in the background every minute. When one of those refreshes fails, it keeps the findings you can already see rather than replacing them, and labels them Not current with the time of the last successful read. Once that read is more than fifteen minutes old, findings that old are no longer useful, so Overview shows the unavailable message instead.

The bluebox command is not found after install​

Open a new terminal, or add the install directory to your PATH for the current session:

export PATH="$HOME/.bluebox/bin:$PATH"

How do I manually uninstall the Bluebox CLI?​

As no bluebox uninstall command is available yet, to uninstall the CLI delete the following directories and files manually.

macOS and Linux

  • ~/.config/bluebox — login and workspace configuration
  • ~/.local/state/bluebox — cache and state files
  • ~/.bluebox — the CLI binary and install channel metadata
  • ~/.local/bin/bluebox — a symlink to ~/.bluebox/bin/bluebox, if it exists

If you set a custom $XDG_CONFIG_HOME or $XDG_STATE_HOME, use those locations instead of the defaults above.

If ~/.local/bin was not already on your PATH when you installed the CLI, the installer added a line to your shell rc file (~/.zshrc, ~/.bashrc, or ~/.profile). Remove that line manually.

Windows

Delete the following directories:

  • %APPDATA%\bluebox — login and workspace configuration
  • %LOCALAPPDATA%\bluebox — cache and state files
  • %USERPROFILE%\.bluebox — the CLI binary and install channel metadata

The installer added %USERPROFILE%\.bluebox\bin to your user PATH environment variable. Remove it via Settings → System → Advanced system settings → Environment Variables.

All platforms

The CLI may also have written skill files and instrumentation templates to agent-specific locations that cannot be listed exhaustively here. Check the configuration directories for any coding agents you use.