Getting Started
Version: 6.2 | Last updated: 2026-07-23
Get from zero to your first Bluebox investigation in minutes.
Tip: The whole setup can be driven by your coding agent. Paste the coding-agent prompt from Step 1 into an agent like Claude Code or Kiro and it runs setup end-to-end, prompting you only for the steps that need a browser. Prefer to do it yourself? Step 1 also includes a separate terminal command.
Before you begin
Make sure you have:
- A GitHub account where your repository lives
- A service you can instrument with OpenTelemetry. (If you already have OpenTelemetry instrumentation, it can be pointed to Bluebox's OTLP Ingest.)
New to observability? Observability means capturing data from your running services — traces, error rates, and response times — so you can see their behavior. OpenTelemetry (OTel) is the open standard for collecting and exporting that data. Bluebox connects to it to detect problems automatically and trace them back to their root cause in your code.
New to Bluebox? Open the sign-in page and select Create an account. Tick the box to accept the Bluebox Terms of Use and Privacy Notice, then sign in with your GitHub account. Accepting the terms is required to create an account: if you try to sign in before you have one, Bluebox sends you to the sign-up page to accept first.
If you sign in from a workspace invitation link, Bluebox accepts the invitation during sign-in and opens the invited workspace directly. New members accept the terms on the sign-up page first, then land in the invited workspace. If that workspace has already reached its member limit, Bluebox tells you the invitation can't be accepted until a seat frees up, rather than failing with a generic error.
Step 1 — Install the Bluebox CLI
For an agent-driven setup experience, paste this prompt into your coding agent:
Install Bluebox CLI from https://app.bluebox.ai without piping a remote script into a shell. Download the installer for your platform — https://app.bluebox.ai/install.sh for macOS/Linux, https://app.bluebox.ai/install.ps1 for Windows PowerShell, or https://app.bluebox.ai/install.cmd for Windows Command Prompt — to a local file, show me what it will do, then run it to start Bluebox setup.
If you prefer to run setup yourself, use the installer for your platform:
macOS and Linux:
curl -fsSL https://app.bluebox.ai/install.sh | bash
Windows — PowerShell:
irm https://app.bluebox.ai/install.ps1 | iex
Windows — Command Prompt:
curl -fsSL https://app.bluebox.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
When run interactively in a terminal, the installer starts bluebox setup automatically. The setup flow covers:
- Authenticate with GitHub — your browser opens; approve the request.
- Install coding-agent skills — Bluebox installs its workflow skills into any supported coding agents it detects.
- Open the Setup page — Bluebox opens in your browser to connect your repository and retrieve your ingest token.
To update the CLI to the latest version, rerun the installation command above.
When your workspace is created, Bluebox starts preparing the observability connection automatically when it has the information it needs. You can continue with repository setup while those values are being prepared.
Step 2 — Select a GitHub repository
Select the repository you want Bluebox to monitor and investigate, then click Confirm 1 repo. To switch to a different repository later, return to this page, deselect the current one, and confirm the new selection.
Note: Bluebox currently supports one repository per workspace.
Step 3 — Instrument your services
Bluebox needs OpenTelemetry traces from your server-side services to investigate runtime behavior. The simplest way to add them is to let your coding agent do it — paste this prompt in:
Add OpenTelemetry to this project — use the Bluebox instrumentation skill
The agent follows the installed Bluebox instrumentation skill, which guides it through server-side OpenTelemetry setup. This baseline covers application traces. Metrics and logs can be added when you ask for them and the agent can preserve your existing logging behavior.
OpenTelemetry setup is not the same as full observability coverage. Browser or mobile real-user monitoring, application security, host or Kubernetes monitoring, cloud integrations, synthetic checks, SLOs, dashboards, and alerts each require their own setup path. Bluebox can use those signals when they already exist, but this coding-agent step does not configure them.
What's happening behind the scenes: during setup the CLI writes a .env.otel.bluebox-template file into the repository, holding the exporter settings for your service. The agent reads it, wires the OpenTelemetry SDK to your language and framework, and fetches the OTLP endpoint with bluebox otlp-endpoint when it needs it. You don't have to touch any of this yourself — but if you'd rather wire things up by hand, you can run bluebox otlp-endpoint and edit the template directly. If the command says Bluebox is still preparing the endpoint, wait and retry. If it says manual configuration is necessary, a workspace owner should finish monitoring setup in the Bluebox web frontend before rerunning the command.
If the template file is missing or you want a fresh copy, delete it and run bluebox setup again to regenerate it.
Your ingest token is deliberately left out of the template and every CLI command. Copy it from the Setup page in your browser and provide it to your service through a secret manager or environment variable. Keeping the token in the browser — never in a file or in CLI output — means a coding agent can't capture it and it can't be accidentally committed to your repository.
Verify telemetry is flowing
The Setup page shows your OpenTelemetry endpoint and ingest-token header when they are ready. If Bluebox is still preparing those values, leave the page open; they appear automatically after a few minutes. If Setup says it needs attention, or bluebox otlp-endpoint informs you that manual configuration is necessary, a workspace owner should update the saved connection or connect a monitoring backend with the required access before trying again.
If you're not a workspace owner, the Setup page still shows the connection status correctly once it's ready — you just see a read-only summary instead of the connection form, since only workspace owners can change it.
If you need to issue a fresh ingest token — for example if the current one may have been exposed — a workspace owner can rotate it from the Setup page when the observability connection was set up automatically. Connections configured by hand don't show the rotate option, because rotation relies on the credentials created during automatic setup. Rotating invalidates the previous token immediately, so update any running instrumentation with the new value. The new token appears right away; Bluebox then verifies telemetry ingest in the background and shows progress under the token until it is confirmed.
If the platform token used for the observability connection is approaching its expiry date or has already expired, the Setup page shows a warning or error callout inside the connection step, and the Setup link in the left sidebar shows a warning badge. An expired token blocks new investigations; a workspace owner can update the connection with a fresh token, or you can email Bluebox support at support@bluebox.ai.
Right after a workspace is created, the Setup page notes — just under the ingest token — that the token has not yet been validated for all telemetry data types. This is expected: the connection is ready to use, but Bluebox could not yet confirm ingest for every data type because the environment is still finishing setup. It usually clears on its own within a few minutes. If it persists, a workspace owner can rotate the ingest token from the Setup page, or you can email Bluebox support at support@bluebox.ai.
When the earlier setup steps are complete, the Start analyzing and fixing step stays open so you can continue to Overview while Bluebox waits for telemetry.
Once the Setup page shows your endpoint and token, apply them to your service configuration and run or redeploy. Bluebox waits for telemetry data before marking this step complete.
Note: Instrumentation happens before repository automation because Bluebox needs traces before it can reliably investigate service behavior.
Automatic problem detection
Once telemetry is flowing, Bluebox continuously analyzes incoming OpenTelemetry data and detects when a service is not behaving as expected — elevated error rates, latency spikes, or repeated failures. Detected problems appear as Findings on the Overview page. Select Investigate on any finding to start a Bluebox investigation into what needs to be improved.
Step 4 — Run your first investigation
With your repository connected and telemetry flowing, you're ready.
Open the Investigations page from the sidebar and describe the issue you want Bluebox to look into — paste in an error, reference a service that's been behaving unexpectedly, or just ask what's wrong. Bluebox queries your live observability data, builds an evidence chain, and comes back with an analysis and a proposed fix.
The clearer the description, the sharper the investigation. A good starting point: copy the title and description of an open GitHub issue and paste it directly into the prompt.
When Bluebox is done, it creates a GitHub issue with the full investigation attached — root cause, evidence, and a recommended fix. From there you can take it further yourself or hand it to your coding agent, which can pull the investigation's full context on demand as it works the fix.
Invite teammates to your workspace
Workspace owners invite teammates by email from workspace settings. Bluebox does not send an invitation email. Instead, it creates a join link you copy and share with the teammate yourself — for example over chat or your own email. The teammate signs in, opens the link, and joins your workspace directly.
Invitations expire so old links don't stay valid forever. You choose how long each invitation stays valid when you create it — from 1 to 14 days, defaulting to 7 days. Expired invitations are cleaned up automatically, and the expiry you pick applies only to that invitation.
Each workspace has a member limit. Once the workspace reaches that limit — counting current members plus invitations that are still pending — creating another invitation is blocked until a seat frees up. Remove a member or revoke a pending invitation to make room, then invite again. The invite form shows current members against the limit so you know where you stand before inviting.
Workspace settings keep themselves up to date while the page is open: when a teammate accepts an invitation or someone requests access, the member list, pending invitations, and access requests refresh on their own — you don't need to reload the page.
A teammate who joins by invitation joins your workspace — they don't get a separate one. They can still create their own workspace later from workspace settings if they need one.
Share a link to your workspace
Every page in Bluebox carries your workspace in its address, so you can copy the link from your browser bar — or use the Copy link button on investigation, task, and overview pages — and send it to anyone.
Workspace links share a consistent shape: /w/{workspaceRef}, where {workspaceRef} identifies your workspace. Every workspace page — Overview, investigations, tasks, and chat — lives under that /w/{workspaceRef} prefix, so any link you copy already points at the right workspace. This is the canonical shape for a shared workspace link; older links you saved before this format are still understood and open the same place.
Sharing a link is not the same as adding someone: opening it never grants access on its own. A teammate who is already a member lands on the exact page in the right workspace. Someone who isn't a member yet sees a Request access option instead of a dead end, and the request comes to the workspace owners to approve.
Review access requests
When someone opens a shared link to a workspace they're not in yet, they can request to join it. Workspace owners see these requests in the Access requests list in workspace settings.
Each request shows who is asking — name, email, or GitHub login. Approve adds them to the workspace as a member; Decline leaves them without access. If the workspace is at its member limit, free a seat before approving. The list is searchable and paged, so it stays manageable as requests come in.
To help someone send a request in the first place, the Access requests panel shows your workspace link with a Copy link button. Copy it and share it with the person who needs access — or share a link to any investigation you've shared. When they open it while signed in but not yet a member, they can request to join, and the request appears in this list.
Request access to a workspace
If you open a link to a workspace you're not a member of, Bluebox offers to request access rather than showing an error. A workspace owner then approves or declines your request, and once approved the workspace opens for you.
If you don't have a workspace of your own yet, you land on a full-screen page instead of the app. From there you can request access to the workspace the link points to and wait for an owner to approve, or create your own workspace — nothing is created for you until you choose to.
Create additional workspaces
You can create separate workspaces, each with its own connections and repositories, from workspace settings. Your plan sets a limit on how many free workspaces you can create and own. Joined workspaces do not use that allowance. Pro workspaces do not count against the free-workspace allowance, so upgrading a workspace to Pro frees up your free-workspace slot to create another one.
The Add workspace section shows how many workspaces count against your limit. Once you reach it, the section is blocked with an explanation instead of letting you name a workspace and fail on create. Delete a workspace you own to free up a slot, then create again.
Set your default workspace
When you work across more than one workspace, pick the one Bluebox opens by default. In workspace settings, open the workspace you want and select Set as default workspace. Bluebox remembers the choice across sign-ins. Select Clear default workspace to go back to no fixed default.
Opening Bluebox without a specific link takes you to your default workspace. If you haven't set one, Bluebox opens the workspace you used most recently, or — if you belong to just one — that one. When it can't tell, it shows a chooser so you can pick. A workspace link in the address bar always wins for that browser tab, so a bookmark or shared link opens exactly the workspace it names, no matter what your default is.
If your default or most-recent workspace is no longer available — you left it, or it was removed — Bluebox shows the chooser instead of sending you somewhere you can't open. Signing in for the very first time still gives you your own workspace to start in.
Next steps
- Core Concepts — findings, investigations, chat, and the CLI.
- CLI Reference — every command, flag, and environment variable.
- FAQ — common questions and quick fixes.