Skip to main content

Connections

Version: 4.4 | Last updated: 2026-08-27

Bluebox connects to external services to extend what it can investigate and where it can assist. This page covers the AWS DevOps Agent, Azure SRE Agent, and Kiro integrations.

Managing connection access​

Every connection has an owner: the workspace member who created it. A new connection is private to its owner by default. Other workspace members can see that the connection exists and view its state, but they cannot reconnect it, re-authorize it, change its configuration, or delete it.

The connection's owner can fully manage it: reconnect or re-authorize it, change its settings, change who it is shared with, and delete it. A workspace owner, or any member the owner has granted edit access, can also reconnect, re-authorize, change, and delete the connection. Changing who a connection is shared with is reserved for the connection's owner and the workspace owner; a member with edit access cannot change its sharing.

If you want another member to help manage a connection you own, share edit access with them explicitly. Sharing a connection without edit access lets other members view it but not change it.

This applies to every integration on this page.

AWS DevOps Agent​

The AWS DevOps Agent integration lets Bluebox run investigations against your AWS account.

Once a connection exists, only its owner or a workspace owner can change or remove it. Other workspace members can view its connection state but cannot modify it (see Managing connection access above).

When an SRE investigation runs, Bluebox evaluates registered AgentSpaces and routes sub-investigations to relevant ones. Each AgentSpace contributes root-cause analysis and mitigation proposals incorporated into the final result.

Setup​

Open Setup → Integrations → Add integration and select AWS DevOps Agent. The wizard has three steps:

  1. Configure — Enter a display name and select an AWS region.

  2. Setup IAM — Download the setup script (bash, Terraform, or CloudFormation) and run it with AWS admin and iam:* permissions. The script registers Bluebox as an OIDC provider in your account, creates an IAM role with a scoped trust policy (pinned to the integration's issuer, audience, and subject), and attaches the following permissions:

    Permission groupActions
    Discoveraidevops:ListAgentSpaces
    Task managementaidevops:CreateBacklogTask, aidevops:UpdateBacklogTask, aidevops:GetBacklogTask, aidevops:ListExecutions
    Investigationaidevops:ListJournalRecords, aidevops:SendMessage, aidevops:CreateChat

    The script prints the role ARN when it completes.

  3. Verify — Paste the role ARN. Bluebox stores the connection and runs a token-exchange smoke-test against AWS STS. On success, the integration becomes active. On failure (typically a trust-policy typo or wrong region), the wizard shows the specific STS error so you can fix the role and retry without starting over.

AgentSpaces​

Once the integration is active, click Discover & register to query ListAgentSpaces and see which spaces are available in your account. Select the spaces you want to register with Bluebox.

Fill in the description field for every space you register. Bluebox uses these descriptions to decide whether to involve a given AgentSpace in an investigation. A space with no description is never selected. On a space with no description yet, use Ask AgentSpace to query it directly: the space describes its own purpose and Bluebox drafts the description for you. On a space that already has a description, use Regenerate with AI to refresh it.

Managing an integration​

  • Re-display the setup script: Open Configure → Show setup script. The per-integration client ID is stable for the lifetime of the connection.
  • Edit a space description: Select the registered space, update the description field, and save. Changes take effect on the next investigation.

Removing an integration​

If the connection is active, click Disable on the integration row first. Once the connection is disabled, click Delete. If any investigations are still running, Bluebox rejects the delete. Wait for them to finish, then retry. Bluebox removes the connection and all registered AgentSpaces. The OIDC provider and role in your AWS account are not removed, so remove them manually once nothing else references them:

aws iam delete-role --role-name <role-name>
aws iam delete-open-id-connect-provider --open-id-connect-provider-arn <arn>

Azure SRE Agent​

The Azure SRE Agent integration lets Bluebox run investigations against your Azure subscription.

Once a connection exists, only its owner or a workspace owner can change or remove it. Other workspace members can view its connection state but cannot modify it (see Managing connection access above).

When an SRE investigation runs, Bluebox evaluates registered SRE Agents and routes sub-investigations to relevant ones. Each SRE Agent contributes root-cause analysis and mitigation proposals incorporated into the final result.

Setup​

You need the Azure CLI installed and signed in with permissions to create app registrations and assign roles on the target subscription.

Open Setup → Integrations → Add integration and select Azure SRE Agent. The wizard has three steps:

  1. Configure — Enter a display name and select an Azure region.

  2. Setup Entra — Download the setup script and run it. The script creates an Entra app registration with a federated identity credential (no client secret is stored), creates a service principal, and grants the following roles on your subscription:

    RolePurpose
    ReaderDiscover SRE Agent resources in the subscription
    SRE Agent Standard UserCreate and monitor investigation threads

    The script prints your Tenant ID, Client ID, and Subscription ID when it completes.

  3. Verify — Paste the complete script output. Bluebox extracts the three identifiers automatically. On success, the integration becomes active. If extraction fails (typically because the output is incomplete), the wizard shows a validation hint so you can re-paste without starting over.

SRE Agents​

Once the integration is active, click Discover & register to list SRE Agent resources in your Azure subscription. Select the agents you want to register with Bluebox.

Fill in the description field for every agent you register. Bluebox uses these descriptions to decide whether to involve a given SRE Agent in an investigation. An agent with no description is never selected.

Managing an integration​

  • Re-display the setup script: Open Configure → Show setup script. The per-integration client ID is stable for the lifetime of the connection.
  • Edit an agent description: Select the registered agent, update the description field, and save. Changes take effect on the next investigation.

Removing an integration​

If the connection is active, click Disable on the integration row first. Once the connection is disabled, click Delete. If any investigations are still running, Bluebox rejects the delete. Wait for them to finish, then retry. Bluebox removes the connection and all registered SRE Agents. The Entra app registration is not removed, so delete it manually once nothing else references it:

az role assignment list --assignee <client-id> --query "[].id" -o tsv \
  | xargs -r -I{} az role assignment delete --ids {}
az ad app delete --id <client-id>

Remove the role assignments before deleting the app registration. Azure does not clean up RBAC assignments automatically, so they become orphaned and remain visible in the subscription until explicitly deleted.

Kiro​

Bluebox supports both the Kiro IDE and Kiro Web.

Kiro IDE​

Running bluebox setup detects the Kiro IDE and installs Bluebox skills automatically.

Skills are loaded on demand. Kiro does not load them automatically at session start. To give Kiro Bluebox context in every session without having to ask, add a steering file:

bluebox skills get bluebox-overview > .kiro/steering/bluebox-overview.md

Commit this file to your repository so all team members get the same context automatically.

Kiro Web​

To add production-insight capabilities to Kiro Web, complete the following four steps. Step 1 requires an AWS account administrator; you can do the rest yourself.

1. Enable the required Kiro permissions

Running the Bluebox CLI from Kiro Web depends on Kiro settings that only an AWS account administrator can change. In the AWS Management Console, open Kiro → Settings → Kiro and enable:

  • Autonomous agents — lets Kiro run the Bluebox CLI (downloading it and running bluebox ask) without asking you to approve each command.
  • Web search and web fetch tools — lets Kiro download the Bluebox CLI from the links below.

Without these, Kiro Web cannot download or run the Bluebox CLI, and the production-query steering has no effect.

2. Add steerings

In Kiro Web → Settings → Agent → Steering, create two steerings:

Steering 1 — Download Bluebox CLI

Depending on your OS and architecture, download the Bluebox CLI from:
- Linux (x86-64):    https://app.bluebox.ai/download/bluebox?os=linux&arch=amd64
- Linux (ARM64):     https://app.bluebox.ai/download/bluebox?os=linux&arch=arm64
- macOS (Intel):     https://app.bluebox.ai/download/bluebox?os=darwin&arch=amd64
- macOS (Apple Silicon): https://app.bluebox.ai/download/bluebox?os=darwin&arch=arm64
- Windows (x86-64):  https://app.bluebox.ai/download/bluebox?os=windows&arch=amd64

Steering 2 — Production query with Bluebox CLI

Run the command `bluebox skills get production-query` to get the
relevant Bluebox skill content. Copy the output directly into the Customer
steering field in Kiro.

3. Create a CLI token

In Bluebox → Setup → CLI tokens, create a new token.

4. Add the token to Kiro Web

In Kiro Web → Settings → Agent → Secrets, add a secret:

NameValue
BLUEBOX_TOKEN(token from step 3)

Tokens expire after 30 days. When a token expires, create a new one in Bluebox and update the secret in Kiro Web.