Core Concepts

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

Six concepts cover almost everything you do in Bluebox: workspaces, findings, investigations, chat, the CLI, and proactive use.

Workspaces

A workspace is your shared environment in Bluebox. One is created for you automatically when you sign up. You can create additional workspaces, invite teammates, and switch between them from the workspace menu. Everything in Bluebox — findings, investigations, connections — belongs to a workspace.

Because each workspace has its own web address, you can open different workspaces in separate browser tabs and work in them side by side. Each tab stays on its own workspace, so switching workspaces in one tab never changes what the others are showing.

Workspace owners manage membership and can invite or remove members. If you're added to a workspace, a small blue dot appears on your profile and in the workspace menu until you open it for the first time.

Your default workspace

If you work in more than one workspace, you can pick one to open by default. In workspace settings, open the workspace you want and select Set as default workspace. Bluebox remembers the choice across sign-ins, so opening Bluebox without a specific link takes you straight there. To go back to no fixed default, select Clear default workspace.

When you open Bluebox, it decides where to land in this order:

• A workspace link in the address bar wins — that tab opens exactly the workspace the link names.
• Otherwise, your default workspace, if you set one.
• Otherwise, the workspace you used most recently.
• Otherwise, if you belong to just one workspace, that one.
• Otherwise, Bluebox shows a chooser so you can pick.

A workspace link in the address bar is authoritative for its own browser tab. Opening or switching to a different workspace in another tab never pulls this tab away from the workspace its address names.

If your default or most-recent workspace is no longer available — you left it, or it was removed — Bluebox ignores the stale choice and shows the chooser instead of sending you somewhere you can't open.

Findings

Bluebox continuously monitors your connected environment and automatically detects issues as they occur. Each finding is placed in context — mapped to your services and codebase — so you understand what's affected before you act.

Open findings are listed on the Overview page. From there you can start an investigation directly into any finding with a single click — select Investigate on the finding's row.

Investigations

An investigation is how Bluebox goes deep on a problem. Where chat gives you a fast answer, an investigation works the problem end to end: it traces the issue through your service topology, forms and tests hypotheses, and assembles evidence from your live telemetry — then hands back a structured, evidence-backed result you can act on. This is the core of the Bluebox SRE agent.

Where to start an investigation

There are two ways in, depending on what you already know:

• From a finding. When Bluebox has already detected a problem, open the Overview page and select Investigate on the finding's row. Bluebox starts with the finding's context already loaded — the fastest path.
• From the Investigations page. Open Investigations from the sidebar, select New investigation, and describe the incident in your own words: paste in an error, name a service that's misbehaving, or ask what's wrong. Use this when you have a symptom but no finding yet. (You can start the same way from the Overview page.)

The clearer your description, the sharper the investigation. Copying the title and body of an existing GitHub issue into the prompt is a good starting point.

What Bluebox does

Bluebox works through the problem in visible phases — getting situational context, forming and testing hypotheses, investigating the evidence, and reporting — and streams its progress to the investigation timeline as it goes, with a short summary for each phase it completes. You can watch the evidence it gathers build up in real time, keep the tab open, or come back to it later.

What you get

When an investigation finishes, it produces an evidence-backed root-cause report on the investigation's page:

• Root cause — what actually went wrong, stated plainly.
• Evidence — the specific telemetry behind each step of the diagnosis, not a log pattern-match. Every claim traces back to a signal.
• Affected services and endpoints — where the problem shows up in your topology.
• A recommended fix — concrete guidance you can implement yourself or hand to your coding agent.

By default Bluebox also files the result as a GitHub issue in your connected repository for actionable findings, so it lives where your team already works — you can comment on it, assign it, or paste it straight into a coding agent to open a pull request. Whether an issue is filed follows the workspace's GitHub issue policy (smart by default; always or never available): smart skips inconclusive runs and repeat firings of an already-open problem. Your coding agent can pull the investigation's full context on demand while it works the fix.

What to investigate

Reach for an investigation whenever you need a diagnosis backed by evidence rather than a quick answer:

• A spike in errors or latency on a service, especially after a deploy.
• A recurring failure you've seen in the logs but haven't traced to a cause.
• A customer-reported incident where you have a symptom but not the source.
• An open GitHub issue describing unexpected behavior in production.

For quick lookups and exploration — "what are the top findings right now", "is checkout healthy" — use chat or bluebox ask instead, and open an investigation when you need the structured result.

Investigation states

Your investigations are accessible from the sidebar or the dedicated Investigations page. Common states include:

State	Meaning
Open	Ready to be investigated
Investigating	Bluebox is actively working on it
Resolved	Marked as resolved
Completed	Bluebox finished the investigation and produced its final report
Archived	Closed and stored for reference

Chat

Chat is your direct line to Bluebox. Open a new conversation from the sidebar with + New chat and ask anything — analyze the latest error logs, check what the top active findings are, or get a summary of recent activity. Starter suggestions on the Overview page also begin a fresh conversation, even if you used the same starter before.

Conversations are saved and persist across browser sessions, so you can pick up where you left off.

When Bluebox kicks off long-running automated tasks during an investigation, a panel above the message box lists them with their status. Running tasks show progress and a control to stop them; finished tasks let you open their results. You can keep chatting while they run.

Bluebox CLI

Query Bluebox, run setup, and interact with your workspace directly from the terminal. Use it standalone or alongside your coding agent in Claude Code or Kiro.

The most useful command to know:

bluebox ask "<question>"

Ask anything — what the top active findings are, what changed in the last deploy, whether a specific service is behaving normally. Bluebox queries your live observability data and streams the answer back, so it works just as well piped into other tools as it does read directly in the terminal. You can also ask about Bluebox itself — its concepts, setup, or how it handles your data.

See the CLI Reference for more information.

Proactive use

Bluebox isn't only useful when something has gone wrong. Before writing code for a new feature, refactoring a service, or deciding where to focus effort, you can ask Bluebox what your production system actually looks like right now.

bluebox ask "which endpoints in the payments service have the highest p99 latency"
bluebox ask "what are the most common errors in the last 7 days"
bluebox ask "is the checkout flow behaving normally compared to last week"

The answers draw from your live telemetry — real traffic patterns, real error rates, real service dependencies — not your mental model of the code. Paste that output into your coding agent and it writes to the system as it actually is. See Workflows for patterns that combine production insights with investigations and coding agent handoffs.

Sharing links to your work

Every page in Bluebox carries your workspace in its address, so the link in your browser bar is always safe to bookmark or share. Open a saved link later — or send it to a teammate — and it reopens the exact investigation, task, or view in the right workspace, even if you work across more than one. Investigation, task, and overview pages have a Copy link button for this.

Opening a shared link never grants access on its own: you still see only what you're a member of and what has been shared with you. If a link points to a workspace you're not in yet, Bluebox offers Request access instead of a dead end — a workspace owner can then approve or decline your request. While you wait on the request screen, Bluebox checks for approval on its own and moves you into the workspace as soon as an owner approves — no need to reload.

Workspaces you haven't opened yet

When you're added to a new workspace, a small blue dot appears on your profile at the bottom of the sidebar, and the same dot shows next to that workspace when you open the workspace menu. It's a one-time signal that you have a workspace you haven't looked at yet. Open the workspace once and its dot clears for good. If you belong to more than one new workspace, each keeps its own dot until you visit it.

How shared workspaces work

The first time you open a workspace you don't own, Bluebox shows a one-time welcome that names the workspace and its owner and explains how sharing works there:

• Everything you create — investigations, chats — starts private: hidden from other members, not secret. Nothing you create becomes visible to teammates until you choose to share it.
• Sharing an investigation is an explicit action, and it grants read-only access. A member you share with can view and comment, but can't change it.
• Only an investigation's owner or the workspace owner can edit, archive, or otherwise change it.
• The workspace owner has audited access to every investigation in the workspace.
• Chats always stay private to the person who started them.

You can reopen this explanation anytime from the workspace menu: select How this shared workspace works.

Next steps

• Getting Started — set up Bluebox and run your first investigation.
• Workflows — investigate findings, query production proactively, and create fixes with your coding agent.
• Security and Privacy — what Bluebox reads, stores, and will never do.
• FAQ — common questions and quick fixes.