mainbrella

Integrations

Use Mainbrella skill instructions with a coding agent, or connect your application’s tool calls to the HTTP API. Your agent runs locally or in your application; lightweight commands run in Mainbrella’s containers.

Recipes reviewed against linked documentation: . Validate your own setup with the checks below.

Before you begin

Get active access, create a named key at API Keys, and supply MAINBRELLA_API_KEY through your environment loader or secret manager. Keep it out of prompts and source control. The supplied doctor and verification scripts require Node 22+.

Codex

Download and inspect the Mainbrella skill archive (0.1.0). Extract its folder into your project’s .agents/skills/ directory; it includes the API contract and indexed references. Invoke $mainbrella-containers and give Codex a concrete task:

$mainbrella-containers
Integrate Mainbrella with this project's existing command tools.
Run the read-only doctor first. Verify hello output and binary
file transfer, then stop only the generation verification created.
Preserve existing containers and report any cleanup failure.

Codex uses the skill to follow the documented HTTP workflow. See official OpenAI skill documentation for skill discovery and invocation.

Claude Code

Download and inspect the same skill archive. Extract its folder into .claude/skills/. Invoke the skill with:

/mainbrella-containers
Integrate Mainbrella with this project's existing command tools.
Run the doctor, verify foreground and managed execution, cancellation and binary file transfer,
and clean up only the container created for verification.

See Claude Code’s skill documentation for project and personal skill directories. The skill sets up remote execution; it does not install Claude Code inside the container.

OpenAI Agents SDK

In an application already using @openai/agents and zod, wrap a Mainbrella HTTP command as a function tool. Download and inspect mainbrella-command.mjs alongside your integration module. Use the exact container generation from your own creation response:

import { Agent, tool } from '@openai/agents';
import { z } from 'zod';
import { mainbrellaCommand } from './mainbrella-command.mjs';

// Bind this inside the lifecycle of a container your app created.
// `created` is the verified ID and createdAt from that operation.
const execute = mainbrellaCommand(created);
const runCommand = tool({
  name: 'mainbrella_command',
  description: 'Run a lightweight shell command in this workspace.',
  parameters: z.object({ command: z.string() }),
  execute: ({ command }) => execute(command),
});
const agent = new Agent({
  name: 'Workspace agent',
  instructions: 'Use the workspace tool for authorized shell work.',
  tools: [runCommand],
});

This code attaches the tool to your existing agent; use your application’s model and runner configuration. Follow Containers to create and reconcile a reservation, bind the returned ID and timestamp in application code, and stop that generation in finally after the agent run. Do not let model-generated arguments select credentials or a different container.

The adapter returns stdout, stderr, exit status, and timeout/truncation flags. Apply your application’s command permissions before execution; tool output becomes available to your agent. It is an HTTP function tool, not a native Mainbrella SDK sandbox provider. See official OpenAI agent and function tool documentation.

Your own agent

Use native HTTP in your existing language. The workflow is the same across frameworks:

  1. Read GET /containers for access, remaining starts, free slots, and available images.
  2. Create with POST /containers and a unique Idempotency-Key. Reconcile ambiguous responses with the same key.
  3. Use the operation’s returned ID and exact createdAt with HTTP execution and file transfer.
  4. Export needed outputs, then stop that generation in finally. Keep its identity if cleanup fails.

The Node command adapter works without an agent framework. It operates on a running generation; creation and cleanup remain your application’s responsibility. See the full HTTP contracts.

Verify your recipe

Follow the Quickstart and run the doctor before verification. A passing verification reports hello output, exit code zero, verified binary bytes, managed streaming, cancellation, and completed cleanup. Verification consumes one start. Then test your agent’s bound command tool with echo hello from mainbrella in a container your application created, confirm those results, and stop it.

All plans offer five machine sizes from Lite (256 MiB RAM) through XL (4 vCPU, 12 GiB RAM). Choose a size that fits your workload and monthly compute allowance. Check limits before launching concurrent tasks.