Skip to main content

FAQ

Version: 2.10 | Last updated: 2026-07-22

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 you see the message "This service is not yet available in your region." while signing up, Bluebox 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. By default it also files a GitHub issue for actionable findings. Whether an issue is filed follows 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.

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.

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.

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.

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"