Introduction

Apiary is the control plane for AI coding agents. Run Claude Code, Codex, and Gemini side by side — as a fleet, a DAG, or a debate. Every task sandboxed, every event streamed, every token metered.

This guide walks through installing the CLI, defining your first workflow, and running it locally. Apiary is currently in private beta — the docs below reflect what's shipping for early-access users.

Heads up

Apiary runs locally by default. Your source, your API keys, and your model traffic stay on the machine that invoked apiary up.

Installation

Install the CLI with Homebrew (macOS / Linux) or with the install script.

shell

$ brew install apiary/tap/apiary

Or, with curl:

shell

$ curl -fsSL https://apiary.run/install.sh | sh

Verify the install:

shell

$ apiary --version
apiary 0.1.0

Quickstart

Initialise a project. This creates an apiary.yaml manifest, a workflows/ directory, and a local state store under .apiary/.

shell

$ apiary init my-project
$ cd my-project

Start the control plane:

shell

$ apiary up
> Orchestrator online on :7878
> Agents connected: claude-code, codex, gemini
> Telemetry streaming to ./.apiary/events.ndjson

Open http://localhost:7878 for the dashboard, or run workflows from another terminal with apiary run <workflow>.

Agents

An agent is a model + tool surface + system prompt. Apiary ships with adapters for Claude Code, Codex, and Gemini, and you can register your own by pointing at any OpenAI- or Anthropic-compatible endpoint.

Agents are declared in apiary.yaml:

apiary.yaml

agents:
  - id: planner
    type: claude-code
    model: claude-sonnet-4-6
  - id: builder
    type: codex
    model: gpt-5-codex

Workflows

A workflow defines how agents collaborate. Three execution modes are supported out of the box.

dag — explicit edges between agents. Best for review or pipeline tasks.
fleet — run the same task across N agents in parallel and compare results.
debate — agents critique each other's outputs until a quorum agrees.

workflows/feature.yaml

name: feature-landing-page
mode: dag
edges:
  - planner -> builder
  - builder -> reviewer

Sandboxes

Every task runs inside an isolated sandbox. By default Apiary uses a per-task ephemeral container with a scoped workspace mount and an outbound network allowlist. Sandboxes are torn down when the task exits; their filesystem diff is persisted as an artefact.

Override the sandbox backend per-agent if you need a different isolation boundary (e.g. backend: firecracker for VM-level isolation).

Configuration

Configuration is loaded from apiary.yaml in the project root, with environment variables and CLI flags taking precedence. Secrets (API keys) are read from .env or your system keychain — never written to the manifest.

apiary.yaml

project: my-project

runtime:
  sandbox: container
  max_parallel: 4

telemetry:
  otlp_endpoint: http://localhost:4317

CLI

The CLI is the primary entry point. Common commands:

Command	Description
`apiary init`	Scaffold a new project.
`apiary up`	Start the orchestrator in the foreground.
`apiary run <workflow>`	Execute a workflow against the running orchestrator.
`apiary logs`	Tail the structured event log.
`apiary agents`	List registered agents and their status.
`apiary keys`	Manage API keys for agent providers.

Looking for something that isn't here? The beta is still small — open an issue on GitHub and we'll get to it.