Skip to main content
This guide takes you from a Blue release to a governed agent launch without choosing an infrastructure platform for you. Blue runs as standard container workloads backed by PostgreSQL and S3-compatible storage. You can use the provided Helm chart, deploy the containers with another scheduler, or evaluate the system with Docker Compose. The first deployment uses governance-only mode. Developers keep their native provider credentials while Blue manages agent policy and extensions. You can add an organization-operated inference gateway later.

​
Prerequisites

Every deployment needs:
  • PostgreSQL and two S3-compatible buckets: one for immutable package artifacts and one for session objects
  • Public HTTPS origins for the dashboard and Control API
  • Secret delivery for database, authentication, and storage credentials
  • A platform that can run the Blue container image and provide private service-to-service networking
  • At least one supported coding-agent CLI, configured with native provider credentials, for the final workstation test
1

Download a release

Choose a GitHub Release, then download and verify its deployment bundle:
The bundle contains a starter blue.yaml, the Helm chart, an AWS OpenTofu module, and optional gateway-provisioner examples. Deploy the stock Blue image by immutable digest; package a custom provisioner separately if gateway mode requires one.
2

Choose how to run the services

The application contract is the same on every platform. Your TechOps team owns placement, networking, secret delivery, scaling, and rollout policy.

Kubernetes and Helm

Use the maintained chart and optional AWS OpenTofu starter as a reference production implementation.

Your platform

Map the image commands, ports, health checks, configuration, and dependencies onto ECS, Nomad, VMs, or another scheduler.

Local evaluation

Run the reference stack with Docker Compose before designing a production deployment.
Docker Compose includes development credentials and trusted-network settings. Use it to evaluate Blue, not as an unchanged production template.
3

Provide the common deployment contract

Whichever platform you choose, deploy these governance-only workloads:Mount blue.yaml read-only at /etc/blue/blue.yaml, deliver runtime secrets as environment variables, and connect every workload to the same PostgreSQL database. Give the Control API and worker access to both object-storage buckets. Keep credentials out of the image and configuration file.Follow the Deployment contract for the complete process, port, health-check, networking, and lifecycle requirements.
4

Configure policy, identity, and storage

Start from the bundle’s governance-only blue/blue.yaml. Replace the organization and public-domain placeholders, configure internal dashboard authentication URLs, and select the allowed harnesses. Add the optional top-level gateway section or governance.session_upload only when enabling that feature.At minimum, supply:Use Configure blue.yaml for the full schema, value precedence, and secret-reference rules. The mounted file is a deployment baseline; administrators can publish later policy revisions from the dashboard.
5

Start and verify the services

Start PostgreSQL and object storage first, then the dashboard, Control API, and singleton worker. Configure your load balancer or reverse proxy to terminate TLS and route the two public origins.Verify the public endpoints using your own domains:
The Control API should return ok, and the dashboard health endpoint should succeed. Also verify that the Control API readiness check can reach PostgreSQL and that the worker remains healthy. Platform-specific rollout checks belong in your deployment implementation.
6

Sign in as the bootstrap administrator

Open the dashboard origin and sign in with the bootstrap email and password from your secret system. Confirm that the dashboard shows the expected organization, allowed harnesses, and initial policy.Invite another user from Members, or continue with the bootstrap administrator for the first workstation test. See Manage users and invitations or Identity provisioning for managed OIDC and SCIM.
7

Install the workstation CLI

On a workstation with Codex, Claude, Kimi, or OpenCode already on PATH, install Blue:
The installer downloads the matching release asset, verifies it against SHA256SUMS, and installs blue in your user path. Set BLUE_VERSION=0.1.0 to pin a specific release.
8

Connect and launch an agent

Connect to the public Control API, authenticate, and choose an installed harness:
Enter https://api.blue.example.com when blue setup asks for the deployment origin. Replace codex with claude, kimi, or opencode as needed. Running bare blue launches your preferred eligible agent.
The public health endpoints succeed, the dashboard accepts an administrator login, blue status reports matching desired and applied revisions, and the native agent opens under the deployed policy.

​
Optional: enable gateway mode

Gateway mode adds the inference proxy, an organization-operated LiteLLM gateway, credential provisioning and encryption, private resolver traffic, and session-bound inference JWTs. It does not change the core dashboard, Control API, worker, PostgreSQL, or object-storage contract. Follow Bring your own gateway for the routing model, Gateway access for operator configuration, and the Deployment contract for the additional workload requirements.

​
Next steps

Deployment contract

Translate Blue’s workload and service requirements to your platform.

Kubernetes reference

Use the maintained Helm chart and AWS infrastructure starter.

Managed extensions

Publish digest-pinned skills, plugins, hooks, helpers, and MCP servers.

Troubleshooting

Diagnose authentication, compatibility, reconciliation, and gateway failures.