Ringleader examples
Ready-to-run examples for Ringleader: persistent,
reproducible development environments for people and the AI agents working
alongside them.
Every example is a real manifest you can apply, and -f takes a URL as readily
as a local path, so you can run any of them without cloning anything first.
rl apply -f https://raw.githubusercontent.com/ringleader-dev/ringleader-examples/main/getting-started/01-hello-workstation/workstation.yaml
Copy one, change what you need, and it is yours.
Start here
New to Ringleader? These build on each other, in order.
Stacks
Everything a developer expects for one kind of work, with the coding agent of
your choice already installed. Pick a stack, pick your agent, paste three lines.
| |
|---|
| Front-end | Node.js, Playwright and the GitHub CLI, with an optional React starter app |
Environments
Complete, purpose-built setups.
| |
|---|
| AI coding agent | Claude Code or Codex in a governed box, signing in through your own browser |
With other tools
Ringleader alongside tools you may already use. These are ours, not theirs: we
are not affiliated with the projects below, and each example says so.
| |
|---|
| Stacklok ToolHive | Host MCP servers in a workstation that has the container runtime they need |
| dltHub | Have your agent build a dlt data pipeline, in an environment as reproducible as the pipeline |
Applying by URL
Each example gives you its commands with its own URL already filled in, so
nothing you run needs a file on disk. rl diff -f and rl workstation delete -f
take a URL on the same terms, which means you can preview an example before
running it and remove it afterwards without ever cloning this repository.
rl diff -f https://raw.githubusercontent.com/ringleader-dev/ringleader-examples/main/getting-started/01-hello-workstation/workstation.yaml
Two things worth knowing. The link has to be the raw one: a
github.com/.../blob/... address serves the HTML page around the file, and
applying that fails with a YAML parse error that does not explain itself. The
Raw button on any file here gives you the right link. And these URLs point at
main, so an example can change under you. Swap main for a commit SHA to pin
one to a version that will not move.
To edit an example rather than run it, take a copy:
git clone https://github.com/ringleader-dev/ringleader-examples.git
The idea
Describe the machine, the tools, and the agent your project needs in one file,
then apply it. Ringleader builds the same environment every time, on your laptop
or in your cloud. Hand the file to a teammate and they are running in minutes.
Give an agent exactly the tools and access it needs, and nothing else.
Three things show up across these examples:
Two resources, deliberately separate. A Workstation is an instance, the
machine itself. A WorkstationConfig is a reusable layer of software and settings that
finds machines by label, not by name. That indirection is what lets one config
equip a whole team.
Ready is not Configured. Ready means the machine is up. Configured
means your declared setup has actually landed on it. After a config change, wait
on Configured.
Nothing reaches your machine unless you ask. Port forwarding and
browser-open passthrough are opt-in, per environment. That is why the browser IDE
and the coding agent each declare what they expose. The same applies in reverse:
if an example expects you to sign in to something inside the box, it has to
declare the passthrough-www-browser devtool and a LocalBinding, or the
sign-in page has nowhere to open.
Requirements
Ringleader installed, and the rl CLI on your path:
rl version
If not, start with the installation guide.
The getting-started examples run entirely on your own machine, with no cloud
account needed.
Conventions
- Examples use the reserved
local namespace, so they run against your
machine's own runtime and never touch a control plane. The cloud variants name
no namespace at all, so they land in the one your login gave you.
- The base image is pinned on every example that assumes anything about the
distribution, and third-party tool versions are pinned.
An example that silently changed under you would not be much of an argument
for reproducibility. Each README says where to bump.
- Every example includes its clean-up command, and it deletes by manifest
(
rl workstation delete -f <manifest> -y) rather than by name. A manifest usually
declares more than a machine, and deleting the machine alone leaves the config
behind to attach itself to whatever you create next.
Contributing
Issues and pull requests are welcome, especially:
- an example pairing Ringleader with a tool you use
- a correction where an example has drifted from reality
Keep an example runnable end to end, explain why rather than only what, and
pin versions.
Licence
Apache 2.0. Copy these into your own projects freely.
