Skip to main content

Documentation

Every guide here belongs to one audience package. Below is every section of every package, in reading order, so you can go straight to the part you need.

Operator​

Configure, run and monitor AI workflows from the admin console, no code required.

Getting Started​

Before you touch a single setting, get the mental model everything else rests on. Circus is a decision instrument that happens to run AI workflows — change a model or a prompt and read the effect on cost and quality directly — and plugins are how your own domain becomes something the platform can manage. Start here to understand what you're really working with.

Your Account​

The practical front door: getting into the platform and keeping your access under control. This is where you set up your account, manage sessions, and turn on protections like two-factor authentication, so you can work knowing the door is locked behind you.

Configuration​

This is where you assemble your AI staff. Treating agents as employees, you set the environment they work in, choose the models that power them, define their roles, write their jobs as versioned prompts, and bundle it all into configurations you can swap at will. The lesson that carries through everything: you change behavior here, in configuration — never by editing the workflow itself.

Services, Engines & Workflows​

Workflows don't run in a vacuum — they call outside vendors and execute on an engine. This section wires those pieces together and ends on the single most important operational idea: everything is connected. Disable a model, a prompt, or a service and the effect cascades downstream until you resolve it, which is exactly what keeps the platform from running in an invalid state.

Running Workflows​

The payoff of all that configuration: actually running work. This section answers the question everyone arrives with — how do I run a workflow — and explains the workspace, the versioned space a piece of work lives in, where its status quietly decides what you're allowed to do next.

Working with Entities​

How you operate on a real piece of work, day to day. Shown through the default plugin's Things, you'll learn to manage, organize, branch, and finalize your work. Because this experience is delivered by a plugin, your own custom plugin may present it differently — but the underlying shape you learn here carries over.

Monitoring & Cost​

This is where Circus earns its keep. Every run leaves an honest trail, and this section teaches you to read it — what happened, whether you can safely retry, what it cost, and how it all rolls up on the dashboard. This is the production-economics data that turns "AI feels cheaper" into a decision you can actually defend.

Demo​

See the whole platform work as one connected thing. This guided walkthrough configures everything in the right order and runs a real pipeline end to end, so the concepts stop being separate features and click into place as a single, coherent experience.

Ops Engineer​

Provision, deploy, secure and operate a Circus server, release by release.

Setup & Provisioning​

Standing up Circus for the first time. This section takes you from a bare server to a solid, correctly-wired foundation — Docker, networks, DNS, environment configuration, and the reverse proxy that fronts it all — so everything above it has a dependable home.

Deploying & Releasing​

How code becomes a running deployment, safely and repeatably. This section covers the pipeline that ships it, the strict order migrations must follow, how versions and releases are cut, and how to roll back when something goes wrong — the discipline that keeps staging and production trustworthy.

Day-2 Operations​

Everything after the first deploy: the ongoing care and feeding. Routine Docker operations, engine and n8n specifics, the monitoring and reconciler that keep the platform and its engine in sync, and a clear line on where the platform's responsibility ends — it orchestrates work, but it doesn't manage your stored assets.

Hardening & Customization​

Making the deployment both safe and yours. This section locks the server down, rebrands the platform for your organization, and shows how to fork it cleanly for self-hosting — the steps that turn a generic install into a secure, owned product.

Architect​

How the platform is built: domain and plugin model, execution and cost, integration and auth.

System Overview​

The view an architect wants first: what the pieces are, how a request flows between them, and where the firm line between core and plugins falls. This section establishes the platform's fundamental shape and the single invariant that lets it be extended without becoming entangled.

Domain & Plugin Model​

How the platform models the world and lets others extend it. You'll learn the domain model of entities, workspaces, and statuses, the extension model that clips a new domain onto the core, and how configuration lineage and the disable-cascade keep the whole system's state coherent rather than drifting into contradiction.

Execution & Cost​

What actually happens when a workflow runs, and how the platform stays honest about it. Immutable snapshots make every run reproducible, a clear status machine tracks its fate, two layers enforce cost and time limits, and a reconciler guarantees the platform is never confidently wrong about a still-running execution. This is the machinery behind the platform's credibility.

Integration & Auth​

How Circus talks to the outside world and proves who's talking. This section covers the engine integration model, the layered credentials that authenticate each direction, the deliberate split between human and machine authentication, and the four distinct API surfaces — the trust and communication boundaries of the whole system.

Data Model, Diagrams & Reference​

The authoritative reference you reach for to check a claim: the canonical glossary, the platform's invariants stated plainly, and the ER and auth diagrams reproduced faithfully. These pages are deliberately as-precise-as-the-source, because at this altitude accuracy is the entire point — and it's what tells a reading architect that real architects were on the other side.

Plugin Developer​

Bring your own domain into the platform by building a plugin against the core contract.

Overview​

Orientation for building your own plugin. This section frames a plugin as an app within the app that brings your domain to life, names the concepts you'll need before diving in, and sets two habits from the start: build for the operator, who is effectively your customer, and remember the possibilities are wide open as long as you respect a few simple rules.

Understanding Plugins​

The conceptual core of plugin development. You'll walk the manifest, the contract you must satisfy, the data model, and the four extension points, then study the reference plugin to see how the pieces actually fit together — which naturally raises the questions the later sections go on to answer.

Database & Results​

Making your plugin real in the database and wiring it into a running workflow. This section covers writing migrations, handling workflow results inside the platform's transaction so your data and the workspace status commit together, and how the loader discovers and validates your plugin at startup.

Getting It to the Operator​

Turning a working backend into something an operator can actually use. This section covers consuming core services, building your UI inside the core shell, exposing your API, and testing it all — the last mile from "it runs on my machine" to "it ships."

Guardrails, Build & Troubleshooting​

The boundaries and the finish line. This section states plainly what a plugin may never do — the few rules that keep the freedom safe — then walks you through building your first plugin end to end and diagnosing the failures you'll most likely hit along the way.

Reference​

The lookups you'll return to again and again: the full core API you integrate against, and the reference plugin's business rules. When you're unsure how something behaves, this is where you come to check.

Workflow Developer​

Build n8n workflows that read the Circus payload, call services and report results and cost back.

Getting Started​

Before you build anything, understand the job. A workflow in Circus is an accountable, operator-controlled member of the team — you build the pipeline, the operator tunes the intelligence — and this section sets that framing, then gets you set up with the nodes installed and a clear map of what each one does.

The First Steps​

Every Circus workflow needs a proper entry point, and this is it. You'll place the webhook trigger, secure it, and add the Init node that establishes the shared context every downstream node depends on — plus the credential that lets your workflow talk back to the platform. Get this right and everything after it just works.

Reading the Payload: Snapshots​

Everything your workflow needs to do its job arrives in the webhook payload, frozen as immutable snapshots. This section teaches you to read them — and the habit that follows from it: never hardcode what the operator is meant to control. If something you need isn't in the payload, that's a conversation with the operator, not a constant in your code.

The Agent Node​

The heart of AI work in Circus. This section takes the Agent node apart field by field — credentials, the agent slug and its assigned prompt, the runtime input, system context, and its automatic logging and self-termination — showing how genuinely operator-controlled AI works without a single hardcoded model or prompt in your workflow.

Calling Services​

For everything that isn't an LLM call, you build the request yourself. This section explains honestly why there's no dedicated service node, then shows the pattern — make the call, log the usage, handle the errors — that keeps even a hand-built service call fully accountable to the platform.

Reporting Back​

This is what separates a production workflow from a proof of concept. The section first makes the case for why the organization tracks cost and time at all, then shows how your workflow reports its consumption, respects its limits, and stays in sync with the platform. Do this well and your work becomes the very data the business makes its decisions on.

Finishing & Errors​

How a workflow ends — cleanly on success and deliberately on failure. This section covers the Terminate node for error branches and the single Complete node that closes the happy path, along with the placement rules that prevent the most common and most damaging mistakes.

Reference & Demo​

The lookup and the payoff: a practical tour of the machine API from your workflow's point of view, and a pointer to the full demo you can run yourself to watch every piece work together end to end.