Skip to main content

Plugins, Explained

Out of the box, Circus doesn't know what you work on. It has no built-in notion of a video, a lead, a document, or a support ticket. That's deliberate: the core platform is domain-agnostic, and the thing that gives it a concrete domain is a plugin.

What a plugin is​

A plugin teaches Circus about one kind of thing you want to process — your entity — and how to work with it. It supplies the entity's data, the pages you manage it on, the statuses it moves through, and the logic that runs when a workflow finishes. Everything domain-specific you see in the app comes from a plugin; the core provides the surrounding machinery (configuration, execution, cost tracking, dashboards) that's the same no matter what you're building.

The default plugin, and your own​

Circus ships with a default plugin whose entity is a generic "Thing." Its real purpose is to be a complete, working example — a reference that demonstrates everything a plugin can do. It's generic enough that a simple use case might run on it as-is, but that's a convenience, not the intent.

For a real domain, you'll want a custom plugin — one that defines your entity (a Video with a script and a render status; a Lead with a score; a Document with a template) and the behaviour around it. The rest of the platform — models, agents, prompts, workflows, cost analytics — works exactly the same underneath; the plugin just gives it your domain's shape.

How you get one​

A plugin is software. Building one is a development task: it means writing a plugin against the platform's plugin contract, following the same pattern the default plugin demonstrates. So if you need a custom domain, that's a job for a plugin developer — someone on your team, or any qualified Node.js software engineer who can follow the plugin development guide. As an operator you don't build the plugin, but it's worth knowing where the line falls: the plugin defines what you manage and how its pages look, and you configure how the AI does the work.

One practical consequence: because your entity's management screens come from a plugin, the operator articles here that describe "working with entities" are written against the default plugin. A custom plugin for your domain may lay things out differently — the concepts carry over, but the exact screens are the plugin developer's design.