Skip to main content

FAQ

Version: 5.5 | Last updated: 2026-11-13

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

Get started​

Do I need to write any agent code?​

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

Which coding agents does Bluebox support?​

Bluebox works with any modern MCP client. Agents that support MCP sign-in connect with the server URL alone and a browser approval. Other agents connect with an access token. See Connect a Coding Agent for the steps for each agent.

How do I authenticate Bluebox with my coding agent?​

Bluebox supports MCP sign-in and access tokens, and sign-in is recommended when your agent supports it. Add the Bluebox server URL, and the agent opens your browser so you can approve access. Use an access token when your agent does not support sign-in. Existing token connections keep working, and moving them to sign-in is recommended. See Connect a Coding Agent.

How long does an agent's connection to Bluebox last?​

A connection made with MCP sign-in ends when you revoke it, after 14 days without use, or 90 days after you approved it. The agent then asks you to approve it again in your browser. This is separate from your own browser session in Bluebox.

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 three days 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. This holds even if the browser had suspended the tab in the background: the sign-out is handed to the browser itself, so it goes through either way, and you land on the sign-in page.

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 method you used last. For a GitHub account that is one click. For an email account it is the email form: enter your address and Bluebox sends a new link and code. There is no password to remember or reset.

To see where you are signed in, or to sign another browser out, open your profile menu, select Account, then open Browser sessions. Select Revoke on a session to sign that browser out. The session you are using is marked This session; end it with Sign out in the profile menu.

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. Bluebox skips public repositories and ones whose visibility can't be confirmed, and the report says no issue was filed and why. When writes to public repositories are turned on for your workspace (for example, during a workshop), it files there too, and anyone can read those issues.

Why does Bluebox add labels to my repositories?​

So Bluebox can track its own work in your repository: recognizing when it has already filed an issue for a recurring problem, and triggering automated code fixes through connected agents. Before an investigation, Bluebox checks each connected repository it can write to (archived repositories are skipped) and creates whichever of these five labels are missing: sre-investigation, code-fix, needs-investigation, kiro, and still-active. Once Bluebox has seen all five on a repository, it stops checking that repository, so later investigations start without the check. 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, and still-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 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 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. Select 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.

bluebox ask reads files, pull requests, their diffs, and issues in your connected repositories. See the CLI reference.

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 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. The one exception is repository files: the agent lists the files it read, by path, in its own answer, so treat that list as the agent's report rather than recorded evidence. 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.

Troubleshoot​

This section covers sign-in, the CLI, and your account. For setup itself—telemetry that isn't arriving, ingest tokens, the observability backend connection, and repositories—see Troubleshooting.

Sign-in says my email already has a Bluebox account. What now?​

You signed in with a different account than the one your Bluebox account uses, with the same email address. Most often your organization moved you to an enterprise-managed GitHub account, which is a new GitHub identity even though the email is the same. It also happens when you first signed up with one provider, such as GitHub, and now sign in with another, such as Google.

If you sign in to Bluebox with email and now use GitHub or Google with the same address for the first time, Bluebox usually emails a code to that address. Enter the code in the same browser and the new sign-in is added to your account, with nothing to merge. If your account does not use email sign-in, or no code is sent (for example because email sign-in is unavailable or you asked for too many codes recently), Bluebox offers to merge the two instead. Select the sign-in it names and sign in with the account you used before, in the same browser, within 15 minutes. For GitHub, pick your original account when GitHub shows the account picker. Bluebox then asks you to confirm the merge. It moves the workspaces, investigations, and CLI logins of the account you just used into your Bluebox account, and it cannot be undone. Select Not now to keep the accounts separate. If Bluebox cannot offer a merge, it names the sign-in your account uses. Sign in with that instead.

From then on, every sign-in of both accounts reaches the same Bluebox account. That includes two GitHub accounts, such as a personal one and an enterprise-managed one, and the email address of the merged account. Bluebox emails the address on your Bluebox account when a sign-in method is added.

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.

Setup says I signed in to GitHub with a different account. What now?​

Setup is already connected to one GitHub account, and you signed in to GitHub with another one. Bluebox keeps the account Setup is connected to and changes nothing. Renaming your GitHub login does not cause this: Bluebox recognizes the account and picks up the new login.

To connect the account you signed in with, select Use a different GitHub account in that message on the GitHub step, then pick the account on GitHub. From then on you sign in with the new account and the old one no longer works. To keep the current account, ignore the message. Only workspace owners can switch the account; if you are not one, the message asks you to contact a workspace owner.

I signed up with email. How do I connect GitHub?​

You connect GitHub from the Setup page, and you only need it for repositories. Open Settings → Setup, select Connect with GitHub, sign in to GitHub, and then select the repositories Bluebox may read. Without GitHub, Bluebox still works. It just has no code access, ticket creation, or GitHub triggers. Get started lists what you get.

If you choose Continue with GitHub on the sign-in page with the email address of your account, Bluebox does not sign you in straight away. It emails a six-digit code to your address, and the email names the GitHub account being added. Enter the code on the sign-in page to finish. If you did not just sign in to GitHub, ignore the email. A newer code replaces an older one, and the code expires after 15 minutes. After five wrong codes you need to sign in with GitHub again for a new one.

Only workspace owners can change the GitHub repository connection of a workspace.

I signed up with GitHub. Can I also sign in with email?​

Yes. While signed in, open your profile menu, select Account, then open Sign-in methods and select Verify email. Bluebox emails your account's address a six-digit code and a link. Enter the code on that tab, or open the link in the same browser, and email becomes a second way in. You can also start from the sign-in page: enter your account's email address and select Continue with email. After you confirm the link or code, Bluebox asks you to continue with GitHub once, in the same browser. From then on either works. Bluebox emails you whenever a sign-in method is added to your account.

Sign-in says I am signed in as a different Bluebox account​

The sign-out before it did not go through, so the browser still holds the previous session and Bluebox will not attach a second identity to it. Sign out, wait for the sign-in page, then sign in with the account that owns the address.

Sign-in says Bluebox could not read a verified email from my GitHub account​

Bluebox needs a verified email address to create your account. Go to your GitHub email settings and verify one, then try signing in again.

If GitHub refuses with "Email is already verified by another user," that address is already verified on a different GitHub account, most often a personal account you had before your organization moved you to an enterprise-managed one. An address can only be verified on one account at a time, so verifying it here first requires unverifying it on the other account, or asking your GitHub enterprise admin to resolve the conflict. GitHub notifies enterprise admins when these conflicts exist, so they may already have a list. Email us at support@bluebox.ai if you are stuck either way.

My organization uses enterprise-managed GitHub accounts or an IP allow list. What does our admin need to do?​

Two things can stop the first sign-in from such an organization. Send this answer to your GitHub admin.

  1. IP allow list. If your enterprise or organization restricts GitHub access by IP address, sign-in fails with a message that Bluebox is not on the allow list. Your admin adds the Bluebox address as an entry on the IP allow list, under Settings → Authentication security → IP allow list. Email support@bluebox.ai for the current address. An entry on the enterprise applies to every organization it owns. The setting that adds the IP addresses of installed GitHub Apps does not cover sign-in, because sign-in calls GitHub with your own account's token, so the entry is needed even when that setting is on.
  2. Email verification. An enterprise-managed account needs no extra step unless its email address is already verified on another GitHub account, often a personal one. Then sign-in reports that Bluebox could not read a verified email. See the answer above for the two ways to resolve it.

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. Bluebox waits about a second and a half for the server to confirm, then takes you to the sign-in page. The request is handed to the browser itself, so it finishes even if the page has already moved on — you do not have to keep the tab open for the sign-out to take effect.

One message can appear: Sign-out failed. It means the server answered and refused, so you are still signed in. Check your connection and select Sign out again.

If you are handing the browser to someone else and want to be certain, reload the page — landing on the sign-in page confirms the session is gone.

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. If Bluebox can no longer use the installation it has, Setup says so and, for workspace owners, offers Reconnect GitHub and a Reinstall GitHub App link. That message also appears after a temporary GitHub error, so reinstalling is not always needed: it clears the next time an investigation or chat gets a working GitHub token. If Setup instead says your selected repository is no longer accessible, the app is still installed but that repository can no longer be reached. The repository list is hidden until you select Reconnect GitHub and sign in to GitHub; then pick a repository Bluebox can reach in the selector that appears.

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.

Setup says the GitHub connection is turned off​

Someone in your workspace turned off the GitHub connection. Setup shows This GitHub connection is turned off above your repositories. A workspace owner, or whoever manages the GitHub connection, can still change and save the repository selection. While the connection is off, investigations and chats get no access to your repositories. A matching GitHub event is recorded as Run failed on the routine instead of running (see What each outcome means). A workspace owner can turn the connection back on through the Bluebox API. Your saved selection applies again as soon as it is on.

Resolve degraded repositories​

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. In Setup, the repository picker shows the repository greyed out, with a label that starts with "degraded" next to its organization name. If Setup instead shows Reconnect GitHub and no repository list, reconnect first; the repository picker appears afterward.

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 within seconds, when GitHub tells Bluebox about the change. Otherwise it returns at the next check, which runs when a workspace owner, or whoever manages the GitHub connection, opens Setup. A check is skipped if another one succeeded in the last two minutes, and a check that could not reach GitHub is retried the next time Setup opens. 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.

A report or chat says Bluebox could not read a repository​

At the start of every investigation and chat, Bluebox gets access to each GitHub organization whose repositories you connected. When that fails for an organization, the answer names the connected repositories it could not read and why. Bluebox does not describe code, issues, or pull requests it could not read.

What to do depends on the reason it gives:

  • The GitHub App was removed or its access was revoked: reinstall the Bluebox GitHub App on that account or organization.
  • The GitHub App can no longer reach the repository: give the app access to it on GitHub, or remove it from Bluebox.
  • The organization was renamed: select Reconnect GitHub in Setup and sign in to GitHub. Reinstalling the app does not fix this.
  • The GitHub App connection needs repair: email support@bluebox.ai. Retrying does not help.
  • A temporary failure: run the investigation again or ask again in the chat.
  • The GitHub connection is turned off: a workspace owner turns it back on. See Setup says the GitHub connection is turned off.

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 uninstall the Bluebox CLI?​

Run bluebox uninstall—it removes your login, configuration, installed skills, and (on the standalone install channel) the CLI binary itself, and prints the exact paths for anything it can't remove for you.