Skip to main content

Connections

Version: 3.0 | Last updated: 2026-07-09

Bluebox connects to external services to extend what it can investigate and where it can assist. This page covers the AWS DevOps 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, but only the owner can change who a connection is shared with.

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​

Click Delete on the integration row. Bluebox removes the connection and all registered AgentSpaces. The OIDC provider and role in your AWS account are not removed — 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>

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.