FAQ
Version: 3.0 | Last updated: 2026-09-17
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?
Yes. A workspace can connect more than one repository, including repositories owned by different GitHub organizations or accounts. When an investigation traces a problem to a service, Bluebox attaches the repository that service's code lives in automatically. A per-workspace limit caps how many repositories you can connect at once; if you reach it, remove one before adding another.
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 eight hours 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.
Closing the browser is different: your session survives a week of not using Bluebox, and up to two weeks in total before you sign in again. When it does end, the sign-in page greets you with Welcome back and offers the provider you used last, so getting back in is one click.
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.
Why does Bluebox add labels to my repositories?
So the issues it files can be found and routed. Before each investigation, Bluebox checks every repository you have connected and creates whichever of these five labels are missing: sre-investigation, code-fix, needs-investigation, kiro, and still-active. A repository that already has them is left alone. Capitalization does not matter — SRE-Investigation counts as the same label — but a different separator does, so a label you have renamed to SRE Investigation is a different label and the hyphenated one is still created.
Bluebox only ever adds labels. It never edits or deletes one, and it never applies a label to an issue it did not file.
How do I stop Bluebox creating a label?
Delete the label in GitHub. Bluebox remembers the labels it has seen on each repository, so a label that was there and is now gone reads as your decision to remove it, and it is not created again. The opt-out is per label and per repository: deleting kiro from one repository leaves sre-investigation in place, and leaves both alone on every other repository you have connected.
Investigations keep working without a label, so what you give up is the routing the label carried:
sre-investigation— Bluebox no longer recognizes its own earlier issues, so a recurring incident is filed as a new issue instead of a comment on the open one.kiro— automated code fix is never triggered from the issue.code-fix,needs-investigation, andstill-active— triage and filtering only. You lose the ability to filter your board by outcome.
To undo an opt-out, create the label again yourself under Issues → Labels in GitHub. Bluebox sees it on the repository and leaves it alone from then on.
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
Sign-in says my workspace is on a different GitHub account. What now?
Your organization has most likely moved you to an enterprise-managed GitHub account. That is a new GitHub identity, with a new id and a new login, even though the email address is the same, so Bluebox does not recognize it as the account that owns your workspace.
Continue with GitHub again and pick your original GitHub account when GitHub shows the account picker. That signs you in and takes you to Setup, where Use a different GitHub account moves the workspace onto your new account. From then on you sign in with the new account and the old one no longer works.
If your original GitHub account has already been deactivated and you cannot sign in with it at all, email us at support@bluebox.ai and we can move the workspace for you.
Sign-in says Bluebox could not read a verified email from my GitHub account
Bluebox needs a verified email address to create your account. Enterprise-managed GitHub accounts often do not expose one, even though the address came from your identity provider and is verified. If you are on a personal GitHub account, verify an email address on GitHub and try again. Otherwise email us at support@bluebox.ai.
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.
Sign out did nothing, or reports that it failed
Signing out ends your session on the Bluebox server, so it needs a working connection. If the request does not get through, Bluebox tells you the sign-out failed and leaves you where you are — it does not pretend to have signed you out. Check your connection and select Sign out again.
Your session ends only once Bluebox confirms it. Until then you are still signed in, so sign out before handing the browser to someone else.
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.
If you selected the repository through Configure the Bluebox GitHub App and it still does not show up, check whether GitHub marked your selection with a request badge instead of granting it. That happens when you are not an owner of the organization that owns the repository: your selection becomes a pending request, and an organization owner has to approve it in the organization's installed GitHub Apps settings before Bluebox can see the repository. While a request is pending, the Setup picker says an organization owner has to approve the Bluebox app. That message stays in place across a reload or a later visit, for as long as the request is still open, and there is nothing to retry: the request stays open on GitHub until an owner approves or declines it.
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.