Set Up AI Escalation Controller

This guide connects 1stLine by Burava AI Escalation to a controller hosted in your private network.

You need an active plan with AI Escalation enabled before you can create or edit controller connections.

The AI Escalation Controller currently orchestrates OpenCode. Burava publishes the controller image, but the image intentionally does not include OpenCode, MCP servers, CLI tools, model-provider credentials, or your runbooks. You build your own image on top of the controller image and install the exact assistant runtime and tools your responders approve.

Before you start

Prepare:

• access to AI Escalation
• a containerized environment for the controller
• an assistant environment based on OpenCode
• any MCP servers or CLI tools your AI Escalation rules will allow
• an AI model provider supported by your assistant environment
• a decision about which private systems the controller may reach

The public examples repository includes an example extension Dockerfile, Docker Compose example, Kubernetes manifests, OpenCode configuration examples, controller configuration examples, and starter agents and skills.

• AI Escalation Controller example repository
• Published controller image package
• Example extension Dockerfile
• Example Docker Compose configuration
• Example Kubernetes manifests
• Example controller config
• Example OpenCode config
• Example OpenCode agents and skills

1. Create a connection

1. Open AI Escalation.
2. Open Connection Overview.
3. Enter a connection name.
4. Click Create.
5. Copy the generated secret when 1stLine shows Copy this secret now.

Store the secret in the environment where your controller runs. If you lose it, use Rotate secret and update the controller.

2. Decide what the controller may access

Before building the image, decide what the assistant is allowed to inspect.

Common choices include:

• the 1stLine MCP server
• monitoring and log-query tools
• Kubernetes read-only tooling
• internal catalog or ownership lookup tools
• runbook files mounted into the container
• incident or service context fetched through internal APIs

Keep this list narrow. AI Escalation rules can allow MCP and CLI usage, but the controller image and runtime credentials decide what is actually possible inside your environment.

3. Build your controller image

Use the published controller image as the base image. Then add OpenCode and the tools your rules will need.

Your controller image must include:

• the AI Escalation Controller runtime
• OpenCode
• MCP server binaries referenced by your AI Escalation rules
• CLI tools referenced by your AI Escalation rules
• any required runtime configuration or environment variables
• optional baseline OpenCode agents and skills

The public example starts from the controller package image:

ARG CONTROLLER_BASE_IMAGE=ghcr.io/burava-public/1stline-ai-escalation-controller:latest
FROM ${CONTROLLER_BASE_IMAGE}

It then installs OpenCode with npm install -g opencode-ai, installs example MCP servers and diagnostic tools, and copies example agents and skills into OpenCode config locations.

Note

The example Dockerfile is a template, not a required production image. Pin package versions, remove tools you do not need, add your own tools, and use your normal image-scanning and release process.

MCP and CLI enrichments only tell the controller what the assistant is allowed to use by OpenCode Permissions. The actual binaries must already be installed in your image. If a rule allows a CLI tool that is missing from the image, the assistant will not be able to use it.

4. Add OpenCode agents and skills

The public examples include suggested OpenCode agents and skills under example/opencode.

They show how to write general instructions for:

• loading 1stLine assignment context
• pre-flight validation of MCP and CLI tools
• correlating Incidents and Alert Instances
• looking up ownership information
• preparing a response and structured suggested actions

Use these examples as a starting point. For production, replace generic instructions with your team-specific runbooks, service ownership model, escalation policies, and diagnostic expectations.

5. Configure the controller

Use the example controller.config.example.json as a starting point.

Set:

• your controller ID
• the workspace root for assignment files
• the 1stLine API base URL
• the mailbox URL
• the connection secret/token from the 1stLine connection
• assignment timeout behavior
• your OpenCode configuration path
• OpenCode host, port range, startup timeout, health interval, and task timeout
• warm_opencode_servers if you want idle OpenCode capacity kept warm

Keep the controller secret outside source control.

For 1stLine Cloud, the example uses these endpoints:

{
  "firstline": {
    "baseUrl": "https://1stline.burava.com",
    "mailboxWebSocketUrl": "wss://1stline.burava.com/api/ai-escalation/mailbox",
    "taskPathTemplate": "/api/ai-escalation/assignments/{assignmentUid}/task",
    "completePathTemplate": "/api/ai-escalation/assignments/{assignmentUid}/complete",
    "configPathTemplate": "/api/ai-escalation/controllers/{controllerId}/config"
  }
}

From a deployment point of view, the controller is a long-running outbound controller. It opens an outbound connection to the mailbox URL and waits for assignment notifications. You do not need to expose a public inbound webhook for 1stLine to call. The controller does need outbound access to 1stLine and network access to any internal systems used by your MCP servers or CLI tools.

6. Run with Docker Compose

For local testing or a small private environment, start from the example Docker Compose configuration.

At minimum, your Compose deployment needs:

• your custom controller image
• the controller config mounted into the container
• the connection secret provided as an environment variable or secret
• model-provider credentials required by OpenCode
• credentials for any MCP servers or CLI tools you installed
• persistent or inspectable assignment workspace storage, if you want to review assignment files after runs

Use Docker Compose when it matches your operational model. For production systems, many teams will prefer Kubernetes or another managed container runtime.

7. Run with Kubernetes

The public examples include Kubernetes manifests for a namespace, ConfigMap, Secret example, and Deployment.

A Kubernetes deployment should provide:

• the custom controller image you built
• controller config through a ConfigMap or mounted file
• controller secret and provider credentials through Secrets
• network egress to 1stLine
• network access to internal tools the assistant may use
• resource limits that match OpenCode startup and assignment load
• logs retained long enough to debug failed assignments

The controller can run in a private cluster because the assignment path is outbound from the controller to 1stLine.

8. Confirm connection health

1. Open AI Escalation.
2. Open Connection Overview.
3. Confirm the connection shows recent Connected activity.
4. If needed, use Refresh.

If the connection stays disconnected, see AI Troubleshooting.

9. Create a rule and test

After the controller is connected:

1. Create a rule in Rules.
2. Add Conditions and enrichments.
3. Choose Allowed suggested actions.
4. Open an Alert Instance and click Escalate to AI.
5. Review the assignment in AI Escalation Assignments.

When you test, confirm all of these:

• the assignment reaches the controller
• the controller starts or leases an OpenCode server
• OpenCode receives the merged config and generated prompt
• MCP servers and CLI tools referenced by the rule are available inside the container
• the assistant writes response.md
• the assistant writes suggested-actions.json
• the assignment appears in AI Escalation Assignments
• suggested actions appear as reviewable actions, not automatically executed changes

10. Understand assignment files

For each assignment, the controller creates a workspace.

The controller writes:

• .firstline/task.json: the task payload received from 1stLine
• .firstline/prompt.md: the generated prompt sent to OpenCode

The assistant should write:

• response.md: the customer-facing diagnostic response
• suggested-actions.json: structured suggested actions

The ready helper writes:

• .firstline/ready.json: marker that tells the controller output is ready

If response.md and suggested-actions.json exist after OpenCode exits but the ready helper was not run, the controller can validate those files and mark the assignment ready. After successful completion, the controller also exports the OpenCode session to the assignment workspace.

11. Keep the responder in control

AI Escalation returns diagnostics and suggestions. It does not let the assistant complete alert actions by itself.

Allowed suggested action types are:

• resolve
• start_incident
• join_incident
• escalate_to
• escalate_further

1stLine shows these as Suggested Actions. A responder must review and apply them.

Related pages

• Escalate to AI
• Create AI Escalation Rule
• Review AI Escalation Assignments
• MCP Server

OpenCode, Docker, Docker Compose, Kubernetes, GitHub, and other third-party tools mentioned on this page are third-party brands. Burava does not own, represent, or speak for those brands.