Skip to main content

Core Concepts

Version: 7.2 | Last updated: 2026-09-14

Bluebox is built around a small set of concepts. Understanding them gives you a complete mental model of how the product works.

Workspaces​

A workspace is your shared environment in Bluebox — everything (findings, investigations, connections) belongs to one. See Workspaces for roles, membership, defaults, and sharing.

Findings​

Bluebox continuously monitors your connected environment and surfaces issues as they occur, mapped to your services and codebase. See Findings for how to read and act on them.

Investigations​

An investigation works a problem end to end: forming and testing hypotheses, assembling evidence from your live telemetry, and producing an evidence-backed root-cause report. See Investigations for how to start one and what you get.

Approvals​

Some actions Bluebox proposes need your explicit sign-off before Bluebox runs them — for example, an action that can't be easily undone. When this happens, Bluebox pauses and shows you what it wants to do and why; you approve to let it proceed, or deny with guidance so it can try a different approach.

The workspace owner sees a History tab alongside the active queue, listing every approval that has already been approved, denied, or expired unanswered, along with who decided it and when. This history tab is visible to the workspace owner only — other members see just the active queue.

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.

Routines​

A routine runs an agent on a schedule instead of waiting for you to ask. See Routines for how to create, schedule, and manage them.

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.

Each answer ends with an Evidence section: what it actually queried to answer, and where the data was thin or missing. The Evidence stays with the answer: when you reopen the conversation later, it appears in the history beneath the answer it belongs to.

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.

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, and 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, with no need to reload.