Blue

Blue is a project-first framework for building durable agents and the React applications that steer them. Agent code lives in blue/, application code lives in src/, and both use the same session protocol in development and production.

This repository ships the local framework and the authenticated hosted control-plane contract:

• an Eve-style agent layout under examples/hello-agent;
• a blue CLI and TypeScript client SDK;
• an OpenCode adapter plus a credential-free mock harness;
• durable sessions, FIFO turns, idempotency, event replay, runtime fencing, and hibernating WebSockets;
• WorkOS device authentication for the hosted CLI;
• a Blue model gateway that keeps the platform OpenRouter key server-side;
• native local and deployed Slack apps managed through the Slack CLI;
• sub-second content-addressed agent artifacts on a generic Lambda MicroVM runtime image;
• an AccountDO registry for agents, immutable deployments, and aliases;
• one S3 Files access point and mounted workspace per deployed session;
• platform-only AWS adapters for S3, S3 Files, networking, and MicroVMs;
• a 30-template managed-agent catalog across communications, operations, administration, growth, and insights;
• Cloudflare Workers integration tests.

Try It

Create an account, then create a project and its first development access key:

npx -y @opencomputer/blue@latest login
npx -y @opencomputer/blue@latest projects create "My agent"

The project command prints the development key once. Scaffold the application with npm's standard scoped initializer form (which resolves the @opencomputer/create-blue package):

npm create @opencomputer/blue@latest my-agent
cd my-agent
cp .env.example .env.local
npm install
npm run dev

Fill in the project ID and development key in .env.local. The generated layout is intentionally explicit:

my-agent/
├── blue/                 # agents, tools, connections, channels, schedules
├── src/                  # React application
├── blue.config.ts        # project and environment configuration
└── .env.local            # uncommitted project ID and development key

blue dev --remote watches and live-deploys the blue/ side to the project's development environment; Vite runs the React application. The generated npm run dev command runs both processes together. The React SDK exports BlueProvider, useAgent, useProject, useConnection, and useSession. A project has development and production environments from creation. blue deploy --alias production promotes an immutable deployment while preserving deployment history.

The project API exposes sessions, deployments, shared files, tool connections, inbound channels, schedules, agent schema, and access tokens. Session detail adds the durable event log, session-produced files, session data, and secret references; secret values are never returned by the inspection API.

Run Blue directly from npm with Node.js 22 or newer:

npx -y @opencomputer/blue@latest login
npx -y @opencomputer/blue@latest whoami

Install it globally for the shorter command:

npm install --global @opencomputer/blue
blue login

To work from this repository:

npm install
npm test
npm run blue -- demo "hello Blue" --agent-dir examples/hello-agent

The demo starts Blue's embedded Node control plane, creates a session, attaches a local runtime, runs one turn, streams the result, and shuts down. It uses the mock harness by default. Wrangler is not involved.

Create a new agent with:

npm run blue -- init my-agent
npm run blue -- demo "hello" --agent-dir my-agent

Blue compiles blue/instructions.md, skills, and the seeded sandbox workspace into .blue/runtime/, which is the directory passed to OpenCode.

Log in once to use the hosted service and its OpenRouter gateway:

blue login
blue whoami
cd examples/hello-agent
blue dev

WorkOS opens a browser-based device confirmation at the configured AuthKit domain. The CLI stores rotating access and refresh tokens in ~/.config/blue/credentials.json with mode 0600. The platform OpenRouter key never reaches the developer's machine: blue dev proxies local OpenCode model requests through the authenticated Blue API. blue auth openrouter remains an optional user-owned OpenRouter fallback.

Start local development from an agent:

cd examples/hello-agent
blue dev

Run a local session directly from anywhere inside an agent repository:

blue session "inspect the workspace and summarize it"

Blue reuses a healthy development server when one is running. Otherwise it starts an embedded server for the command and shuts it down afterward. Omit the prompt for an interactive, multi-turn session:

blue session

Start blue dev explicitly when the server must remain available for Slack, multiple terminals, or concurrent sessions:

blue dev

blue dev prints a temporary web: URL containing a fragment token. Open it to create, resume, stream, and end local sessions in the browser. The token is valid only while that development server is running and is never sent in the initial page request.

The development server contains a self-contained local HTTP/WebSocket control plane, runtime manager, OpenCode processes, and configured channels. It has no Wrangler, Cloudflare account, Docker, or AWS dependency. Session state and authenticated discovery metadata live under .blue/dev/; ports are selected automatically unless --port or --manager-port is provided. Each session also receives an isolated OpenCode database, so concurrent CLI and Slack sessions do not contend for OpenCode's global database.

Session management commands use the same discovered or automatically started local server:

blue session send <session-id> "now make the change"
blue session inspect <session-id>
blue session list
blue session end <session-id>

blue session create remains an explicit alias. The CLI automatically selects the live development server discovered from the repository. Use --remote to target the authenticated Blue service instead.

When running this repository directly, substitute ../../node_modules/.bin/tsx ../../src/cli/index.ts for blue. The installed package exposes the shorter blue binary.

Tools and connections

Tools are checked-in OpenCode functions under blue/tools/. Connections are separate account authorizations: they can be replaced or revoked without changing agent code, and credentials never become part of an agent artifact.

Add the built-in Gmail tools and their Google connection declaration:

blue tools add gmail

This creates blue/tools/gmail.ts with search, read, modify, and send tools, plus blue/connections/google.json with the required scopes. Blue compiles the tools into .opencode/tools/, so OpenCode discovers them and streams their normal tool events.

Authorize a Google account for local development:

blue connect google
blue dev
blue session "Find unread email that needs a reply"

Blue opens an OpenComputer-branded Composio Connect Link and associates the resulting Google account with your authenticated Blue user. The configured Composio auth config can be Composio-managed for immediate availability or custom when a white-labeled Google OAuth app is ready. The connection is reusable across local agents that declare the same Google service. Google and Composio credentials are never written to the agent repository or passed to its OpenCode runtime. For a deployed agent:

blue deploy
blue connections connect gmail --remote
blue connections list

Remote credentials are AES-GCM encrypted in the account Durable Object. The MicroVM receives only its existing session-scoped runtime token. Custom tools use that token to call Blue's provider proxy, which restricts requests to the provider's supported API origins and refreshes OAuth tokens in the control plane.

Gmail summarizer example

The examples/gmail-summarizer agent is a safe starting point for inbox triage. Sign into Blue once, connect Google, and run the agent:

cd examples/gmail-summarizer
blue login
blue connect google
blue session \
  "Summarize email from the last 24 hours. Group it into urgent, needs reply, informational, and low priority. Do not modify or send anything."

The Gmail starter declares gmail.modify, which supports reading, labeling, drafting, and sending mail. A read-only starter can use https://www.googleapis.com/auth/gmail.readonly in its connection configuration and a corresponding least-privilege platform auth config.

White-label Gmail setup

The Gmail connection follows all four parts of Composio's white-label flow:

1. In the Composio project, open Project Settings → Auth Screen, upload the OpenComputer logo, and set the app title to OpenComputer. This brands the hosted Connect Link for every toolkit in that Composio project.

2. In Google Cloud, enable the Gmail API, configure the OAuth consent screen with the OpenComputer name and logo, and create a Web application OAuth client. Add the production first-party redirect URI: https://managedagents.opencomputer.dev/v1/connections/google/oauth/callback.

3. Configure the Worker with the Composio project API key and the Google OAuth client. The Google client secret and Composio key must be Worker secrets:

   npx wrangler secret put COMPOSIO_API_KEY \
     --config wrangler.production.jsonc
   npx wrangler secret put COMPOSIO_GOOGLE_CLIENT_ID \
     --config wrangler.production.jsonc
   npx wrangler secret put COMPOSIO_GOOGLE_CLIENT_SECRET \
     --config wrangler.production.jsonc

4. Set these non-secret production variables when the public connection origin differs from the Worker request origin:

   {
     "COMPOSIO_APP_NAME": "OpenComputer",
     "COMPOSIO_GOOGLE_OAUTH_REDIRECT_URI": "https://managedagents.opencomputer.dev/v1/connections/google/oauth/callback",
     "COMPOSIO_CONNECTION_CALLBACK_URL": "https://managedagents.opencomputer.dev/v1/connections/google/callback"
   }

Alternatively, create a Gmail auth config in the Composio dashboard and set COMPOSIO_GMAIL_AUTH_CONFIG_ID. The referenced config may be Composio-managed or custom; Blue validates that it is enabled and belongs to Gmail. A Composio-managed config is the fastest way to start, but its authorization flow may show Composio branding and must use Composio's verified default scopes. Adding scopes beyond those defaults can cause Google to block the managed OAuth app. Use a custom config when custom scopes or a white-labeled first-party Google OAuth app are required.

OAuth scopes are an auth-config property, not a per-connected-account property. Blue creates a separate custom auth config for each normalized scope set. Changing or adding scopes does not upgrade existing tokens: affected users must reconnect and approve the new scope set. This lets different users use different permission profiles, but each profile needs its own auth config and each user must explicitly consent to the profile selected for them.

Local Slack

Install and authenticate the Slack CLI, then add Slack to an agent:

blue channels add slack
blue channels connect slack --local

The first command checks in the Slack manifest and Slack CLI hooks. The second creates and installs the agent's local Slack app. Start it with blue dev; Slack CLI supplies its development app and bot tokens to Blue's start hook, and Blue connects over Socket Mode. No tunnel or manually copied token is needed.

Blue immediately shows Slack's native loading indicator, rotates startup messages, and updates the status with reasoning and tool activity. The final reply clears the indicator automatically. Each Slack thread maps to one persistent local Blue session, with the mapping stored under .blue/dev/.

The non-secret app and workspace identity is recorded in .blue/channels/slack.local.json. Slack CLI owns the local tokens in its credential store; they are not written to the agent's .env.

Remote Slack

Deploy the same agent, then create its production Slack app:

blue channels add slack
blue deploy
blue channels connect slack --remote

Blue first reserves a callback for the deployed agent. Slack CLI creates or updates the production app from the checked-in manifest, verifies the callback, and invokes Blue's deploy hook with the resulting bot token. Blue encrypts that token with its platform channel key. It is never written to the repository or sent to the agent MicroVM.

Invite the resulting app to any channel where it should run, then mention it. Direct messages also work. Each Slack thread maps to one persistent remote Blue session. Blue resumes that session's MicroVM for later turns, replies as the agent's Slack app, and suspends the MicroVM after delivery.

Inspect and remove managed connections with:

blue channels list
blue channels disconnect slack --local
blue channels disconnect slack --remote

Hosted Flow

End users need only the Blue CLI and a browser:

blue login
blue whoami
blue agents list
blue deploy --alias production
blue session create "summarize the workspace"
blue session send <session-id> "now make the change"
blue session list
blue session end <session-id>
blue logout

The CLI defaults to https://blue.opencomputer.dev; BLUE_API_URL or --api-url selects another Blue installation. The logged-in WorkOS organization, or the user ID when no organization is selected, is the account boundary for agents, deployments, and sessions.

blue deploy builds the immutable agent artifact locally, requests a platform-owned upload, uploads directly to the returned signed URL, and registers the deployment. It also prints a public agent page with the exact CLI and Slack interaction commands. Session create, resume, suspend, and terminate call the Blue runtime service. The user machine does not require AWS credentials.

Service configuration

The hosted Worker requires:

• BLUE_WORKOS_CLIENT_ID and optionally BLUE_WORKOS_ISSUER / BLUE_WORKOS_JWKS_URL;
• OPENROUTER_API_KEY as a Worker secret;
• BLUE_CHANNEL_ENCRYPTION_KEY as a Worker secret containing a base64-encoded 32-byte random key; this currently protects channel and tool connection credentials;
• BLUE_GOOGLE_CLIENT_ID and optionally BLUE_GOOGLE_CLIENT_SECRET for a Google OAuth desktop client;
• COMPOSIO_API_KEY, COMPOSIO_GOOGLE_CLIENT_ID, and COMPOSIO_GOOGLE_CLIENT_SECRET for white-label Composio Gmail connections;
• optionally COMPOSIO_GMAIL_AUTH_CONFIG_ID to use a pre-created Composio-managed or custom Gmail auth config instead of creating custom scope-profile configs programmatically;
• optionally COMPOSIO_GOOGLECALENDAR_AUTH_CONFIG_ID to use a pre-created Composio-managed or custom Google Calendar auth config for calendar agents;
• COMPOSIO_GITHUB_AUTH_CONFIG_ID to use the pre-created GitHub auth config for public and private repository access. Store it as a GitHub environment secret named COMPOSIO_GITHUB_AUTH_CONFIG_ID in managed-agents-production;
• BLUE_RUNTIME_IMAGE_ARN and BLUE_RUNTIME_IMAGE_VERSION, stored as GitHub environment variables because they are non-sensitive deployment coordinates;
• OC_MANAGED_AGENTS_SECRET, shared only with the OpenComputer API edge, for short-lived organization assertions;
• a DEPLOYMENTS service binding that returns signed platform artifact uploads;
• a RUNTIMES service binding that owns Lambda MicroVM and S3 Files lifecycle.

The managed backend domain is managedagents.opencomputer.dev; customer CLI and dashboard traffic reaches it only through app.opencomputer.dev. auth.blue.opencomputer.dev remains the WorkOS AuthKit domain for direct backend development. Enable CLI Auth in the WorkOS application, then configure the Worker:

npx wrangler secret put BLUE_WORKOS_CLIENT_ID \
  --config wrangler.production.jsonc
npx wrangler secret put OPENROUTER_API_KEY \
  --config wrangler.production.jsonc
npx wrangler secret put OC_MANAGED_AGENTS_SECRET \
  --config wrangler.production.jsonc
npx wrangler secret put BLUE_CHANNEL_ENCRYPTION_KEY \
  --config wrangler.production.jsonc
npx wrangler secret put BLUE_GOOGLE_CLIENT_ID \
  --config wrangler.production.jsonc
npx wrangler secret put BLUE_GOOGLE_CLIENT_SECRET \
  --config wrangler.production.jsonc

Production runtime changes under src/runtime or src/microvm are built by the Build managed agents production MicroVM workflow after they land on main. The workflow packages the generic runtime, uploads an immutable source artifact, creates and validates a new AWS MicroVM image, persists its ARN and version as managed-agents-production environment variables, and dispatches the production Worker deployment. It can also be run manually with promotion disabled to build a candidate without activating it. The repository variable AWS_WORKLOAD_ROLE_ARN must identify the GitHub OIDC deployment role. Runtime coordinates are variables only; the deployment does not fall back to Actions secrets. The build job deliberately does not attach a GitHub environment so its OIDC subject remains the trusted main branch subject; only the promotion job uses the protected managed-agents-production environment.

Generate the channel encryption secret with openssl rand -base64 32. Every remote Slack installation receives a unique callback credential, stored by Blue only as a hash. Slack CLI configures that callback automatically from the agent manifest.

Google local authorization uses a desktop loopback redirect with PKCE. Gmail's gmail.modify scope is restricted, so a public production OAuth app must complete Google's verification requirements. OAuth access and refresh tokens are never returned by the Blue API after connection.

Configure the platform Worker's AWS secrets plus BLUE_AWS_REGION, BLUE_ARTIFACT_BUCKET, BLUE_EXECUTION_ROLE_ARN, BLUE_NETWORK_CONNECTOR_ARN, BLUE_S3_FILESYSTEM_ID, and BLUE_S3_MOUNT_TARGET_IP, then deploy in dependency order:

npm run deploy:platform
npm run deploy:edge:production

GET /v1/auth/config publishes only the WorkOS client ID and device endpoints; no WorkOS secret is shipped in Blue.

Prompt-based session create and session send suspend the MicroVM after a completed turn. Interactive session create keeps it running until the shell exits, then suspends it. Pass --keep when debugging a running MicroVM. AWS provisioning, Depot runtime image builds, and Cloudflare deployment are platform operator tasks.

Test multiple deployed agents

This repository includes hello-agent and reviewer-agent. Deploy and list both:

blue deploy --agent-dir examples/hello-agent
blue deploy --agent-dir examples/reviewer-agent
blue agents list

Start one independent MicroVM session for each agent. Run these in separate terminals to exercise concurrent cold starts:

blue session create --agent hello-agent@production --keep \
  "Describe your role in one sentence"

blue session create --agent reviewer-agent@production --keep \
  "Review this workspace and report the highest-risk issue"

Use the session IDs printed by those commands:

npm run blue -- session list
npm run blue -- session send <hello-session-id> "Create hello.txt"
npm run blue -- session send <review-session-id> "Review that change"
npm run blue -- session inspect <hello-session-id>
npm run blue -- session inspect <review-session-id>
npm run blue -- session end <hello-session-id>
npm run blue -- session end <review-session-id>

Every session has its own MicroVM and S3 Files workspace. The two agents share the platform runtime image while loading different immutable agent artifacts.

Agent Layout

my-agent/
├── agent/
│   ├── agent.ts
│   ├── instructions.md
│   ├── tools/
│   ├── skills/
│   ├── channels/
│   └── sandbox/workspace/
├── evals/
└── blue.config.ts

The complete architecture, AWS/S3 Files deployment path, security model, and delivery phases are in PLAN.md.

Current Boundary

The standalone local control plane, WorkOS device login, token refresh, tenant-isolated Durable Object routing, signed-upload API, runtime lifecycle API, authenticated OpenRouter proxy, deployed Slack routing, and local/remote agent landing pages are implemented.

The platform services own AWS credentials, signed S3 uploads, Lambda MicroVM calls, and S3 Files access points. Versioned checkpoint replacement, permissions, evals, cleanup, and the unified management dashboard remain subsequent milestones.