reef

Contained AI agents on your servers.

One reviewed file decides what an agent can reach and which credentials it can use. reef holds every agent to it, in its own microVM on your own servers.

Open source, MIT license · reef.clawbits.ai

  1. 02The problemWhat changed, and why existing controls miss it
  2. 03The productRoles, microVMs, three controls
  3. 06ProofClawbits, and the runtime underneath
  4. 09AppendixDetail on any of it, one click away

The problem

Agents act on their own

They are long-running software with access to your systems, not chat windows.

They run code and browse
Agents run commands and open websites with no person approving each step.
They hold credentials
A key an agent can read is a key it can print, log or send somewhere else.
Their settings are not a boundary
Anything reaching the agent, including its own input, can talk it out of them.

Appendix: Questions before an agent goes live

The product

What reef is

A policy layer for agents you run yourself. The rules are applied by the runtime, not by the agent.

agentsOpenClaw, Hermesreefroles, records, policy, one consolemicrosandboxmicroVMs, egress control, key substitutionyour serversLinux with KVM, or an Apple Silicon Mac
A role

One file per agent type: image, resources, the domains it may reach, the keys it may use.

A microVM

Every agent gets its own kernel, its own disk and a volume that outlives it.

One binary

No daemon. A command reconciles the VM to the record, then exits.

Your servers

Linux with KVM or an Apple Silicon Mac. MIT licensed, nothing phones home.

Appendix: What a role defines · Architecture

The product

From an approved role to a running agent

A platform team defines agent types. Teams launch agents from them without a ticket.

hermes.tomlapprovedhermes-2hermes-1hermes-3
1Define

The platform team writes a role and merges it.

2Launch

Teams create agents from approved roles, no ticket.

3Run

Each agent runs in its own microVM, held to its role.

Appendix: What a role defines · Where teams use reef

The product

Three controls, enforced outside the agent

None of them depends on the agent's own configuration or good behaviour.

outside the guestagentDNSunlisted names never resolveegress proxythe real key is added herepublished portbound to 127.0.0.1
At DNS, by the runtime

The allowlist is checked outside the guest. A name that is not listed never resolves.

At the egress proxy

A secret is bound to one domain. The placeholder is swapped for the value on the way out.

At the host loopback

Agent ports bind to 127.0.0.1, which no agent can reach, whatever its role allows.

Appendix: Network allowlist · Credentials · Terminals · Browser access

Proof

Clawbits, a team workspace built on reef

Any member launches an agent from the app and it joins their channels. The agents run on the organization's own servers.

The Clawbits reef settings page: one machine running six agents, each with its owner and status, beside a list of recent activity.
One machine running six agents, with their owners, health and recent activity.
Any member can launch one

They pick a role and a machine in the app. No ticket, and no access to the server.

On the organization's machines

Agents run on servers the customer owns, not on Clawbits infrastructure.

Clawbits never connects in

One private git repository is the whole channel between the two systems.

Appendix: What the integration uses · How the systems communicate

Proof

Built on microsandbox

Isolation comes from microsandbox, an open-source microVM runtime under the Apache-2.0 license. We chose it because it combines the four properties agents need in one runtime.

ContainersTraditional VMsmicrosandbox
Own kernel per agentShared host kernelYesYes
Runs standard container imagesYesNot directlyYes
Blocks unapproved domains outside the agentNeeds extra toolingNeeds extra toolingBuilt in
Keeps API keys out of the agentNeeds extra toolingNeeds extra toolingBuilt in

Several runtimes advertise similar features. In our August 2026 review, each alternative fell short on something reef needs. reef adds the layer above: role files, reviewed versions, fleets, durable agent records and one console across hosts.

Appendix: Architecture · Status and limits

Summary

What organizations get

Containment
Each agent is isolated in its own microVM and reaches only approved services.
Governance
Roles are reviewable files, and every agent maps to a role version.
Self-service
Teams launch agents from approved roles without waiting on tickets.
Ownership
Agents run on your servers. reef is open source under the MIT license.

Appendix: Works with what you already run · Status and limits

Appendix

Detail on anything above. Every line jumps straight to its slide, in the PDF as well as the browser.

  1. Questions before an agent goes live
  2. What a role defines
  3. Network access is an allowlist
  4. Credentials stay on the host
  5. Terminals through your SSH CA
  6. Browser access through single sign-on
  7. Updates and secret rotation
  8. Architecture
  9. What each change affects
  10. The terminal console
  11. Where teams use reef
  12. Works with what you already run
  13. Clawbits: what the integration uses
  14. Clawbits: how the systems communicate
  15. Status and limits
  16. Documentation

Appendix

Questions before an agent goes live

Security and platform teams need clear answers. reef turns each one into a setting you can review.

What can it reach?
Only the domains in its role. Opening the whole internet is an explicit setting.
Which credentials can it use?
Keys named in the role stay on the host and work toward one service.
Who approved its setup?
Roles are files in git. Protect the branch and every change is reviewed.
Who can use it?
A sign-on proxy decides who reaches it. A terminal needs a certificate from your SSH CA.
Appendix

Appendix

What a role defines

A reviewer reads it once. Every agent created from it inherits it.

Coding agent
roles/openclaw-coding.toml
Software
OpenClaw, pinned to an exact image digest
Resources
4 vCPU · 8 GB memory · 20 GB disk
Network
openrouter.ai · github.com · api.github.com · registry.npmjs.org
Credentials
An OpenRouter key, usable only toward openrouter.ai
Storage
10 GB that survives restarts and upgrades
Anything not listed is blocked

Checked outside the agent, so it holds even when the agent ignores its own settings.

Keys are references

The agent holds a placeholder. The real value is added on the way out.

Versions are tracked

A new role version flags every agent still running the old one.

Appendix

Appendix

Network access is an allowlist

A role lists the domains an agent may reach. Everything else is refused at DNS, outside the guest, so the rule holds even if the agent ignores its own settings.

DNSagentopenrouter.aigithub.comapi.openai.com
egress = ["openrouter.ai"]

Opening the whole public internet takes an explicit *, and role apply warns when a role asks for it.

Appendix

Appendix

Credentials stay on the host

A secret is a reference bound to one domain. The agent holds a placeholder; the runtime swaps in the value on the way out.

agent$MSB_KEYhostsk-a1f3$MSB_KEYopenrouter.aisk-a1f3
# inside a real agent VM
$ echo [$FAKE_KEY]
[$MSB_FAKE_KEY]

reef secret rotate pushes a changed value into every running agent that binds it. Each agent records the key and the reference, never the value.

Declaring a secret turns on TLS interception for the whole VM, and the shipped roles then skip browser certificate checks. What an egress allowlist costs

Appendix

Appendix

Terminals through your SSH CA

reef adds no accounts, keys or auth of its own. Your certificate authority says who someone is, and reef decides which agents that identity may open.

SSH CAserveanabobana-hermes
No enrollment

Certificates come from the SSO flow your people already use. Nobody registers a key with reef.

Owner, not operator

sshd always runs reef agent serve, which opens an agent only when a certificate principal matches its owner.

Appendix

Appendix

Browser access through single sign-on

reef publishes agent ports on loopback only. Cloudflare Access handles sign-in and cloudflared dials out from the host, so nothing connects in.

Cloudflarereef hostbrowserAccesscloudflaredagent127.0.0.1sign inyour IdPother agentsdenied
  1. The browser opens the agent's hostname, which resolves to Cloudflare.
  2. Access signs the person in with your identity provider, and nothing else.
  3. cloudflared checks the signed token on the tunnel it dialled out from the host.
  4. It forwards to 127.0.0.1, and the agent opens a session under that email.

Cloudflare is one option. Any sign-on proxy that is the only path to the port works.Setup guide

Appendix

Appendix

Updates and secret rotation

A role change builds the new VM and swaps only when it is ready. Secret values come from the store you already run.

roledatahermes v1hermes v2secretsportsvolumeimage
A new role version checks secrets, ports, volume and image first. The data volume carries over to the new VM.
rolereef://vault/api-keyVaultAWS1Passwordhostsk-a1f3
Roles hold references such as reef://vault/api-key. The host resolves them through 1Password, OpenBao or AWS.
Appendix

Appendix

Architecture

reef is a command-line tool with no daemon. Each command updates the agent record, compares it with the running VM and applies the difference.

roles, fleetreviewed in gitreefno daemonmicrosandboxpinned exactlymicroVMone per agent
No daemon

Every mutating command runs one reconcile pass, then returns.

Deterministic planning

A pure function turns 18 cases into five actions: create, modify, start, stop, remove.

One runtime dependency

A single module names a microsandbox type, pinned to an exact release.

Durable records

Agent records outlive their VMs. A VM is rebuilt from its record.

Appendix

Appendix

What each change affects

Volumes are the durable part. Everything else is rebuilt from the record.

ChangeWhat reef doesSystem diskVolumesHost port
Stop and startStops and starts the VMKeptKeptKept
Environment changeRestarts the VM in placeKeptKeptKept
New role versionReplaces the VMReplacedKeptKept
Remove agentRemoves the VMRemovedKeptReleased
Remove with volumesRemoves the VM and its volumesRemovedDeletedReleased
Appendix

Appendix

The terminal console

reef ui shows every agent across your hosts: role version, resources, network policy, ports and history.

reef ui in a terminal showing one OpenClaw agent: role version, image, owner, running state, resources, volume, egress, ports and recent events.
Every host at once

One console merges agents from independent hosts, reached over your own ssh.

Full detail

Role version, image, owner, resources, volumes, egress policy and ports.

Single keys

Start, stop, update, remove and open a terminal into the agent.

Appendix

Appendix

Where teams use reef

Each example matches a role that ships in the repo.

Engineering agent

Works in code repositories and installs packages.

model providerGitHubnpm

Marketing agent

Works in the marketing stack and nowhere else.

model providerHubSpotLinkedIn

One agent per employee

A private Hermes agent per person, each in its own microVM.

model provider

Agents in team chat

Launched from Clawbits, joining your channels as a member.

public internet

Appendix

Appendix

Works with what you already run

Identity
Cloudflare Access, or any sign-on proxy such as oauth2-proxy or Tailscale
Change control
Git and pull request review, with GitHub for the Clawbits integration
Secrets
1Password, OpenBao or AWS Secrets Manager, read when the VM is created
Terminals
Your existing SSH certificate authority
Agents
OpenClaw and Hermes, with roles that ship in the repo
Servers
Linux with KVM and glibc 2.39 or newer, x86_64 or ARM, and Apple Silicon Macs
Appendix

Appendix

Clawbits: what the integration uses

Each thing the product needed maps onto a primitive reef already had.

What Clawbits needed
What it uses
Launch an agent without touching the server
One fleet file per agent, committed to a branch every host pulls
One definition for every agent in the org
The clawbits-openclaw role, reviewed once and pinned to an exact image
An agent that survives a rebuild
Named volumes: it keeps its own key and comes back as the same agent
A terminal only for the person who owns it
owner in the fleet file, checked by agent serve against the certificate
No way in to a customer machine
The host pulls and pushes through its own deploy key; nothing connects in

Identity is a one-time signup token, valid for seven days. The agent spends it at first boot and keeps its own key on its state volume, so the file is dead weight afterwards and a recreate returns as the same agent.

Appendix

Appendix

Clawbits: how the systems communicate

Clawbits writes agent files to your private repository. Each host pulls every 30 seconds and pushes its status back.

private repopulls every 30splatform teamclawbitsrunningmainfleetstatusreef hostagent
Clawbits

One private repository, through a token you scope to it

reef host

The same repository, through its own deploy key

Agent

Outbound only, to the domains its role allows

Inbound

Nothing connects in to the host

Appendix

Appendix

Status and limits

Available today
  • Open source under the MIT license
  • Linux with KVM and glibc 2.39 or newer, and Apple Silicon Macs
  • Roles for OpenClaw and Hermes that ship in the repo
  • The Clawbits integration, over git
Added in 0.15
  • Terminals through the microsandbox SSH server, no per-person enrollment
  • reef reconcile brings agents back after a reboot or a crash
  • reef secret rotate pushes a changed key into running agents
  • reef migrate moves a 0.14 host onto the current runtime, volumes kept
Known limits
  • Secret values sit unencrypted on the host, in two places; reef doctor warns
  • No HTTP API yet, and it will not ship without auth
  • A role upgrade replaces the system disk; volumes carry over
  • microsandbox is pre-1.0, pinned exactly, with no support for older releases
Appendix

Appendix

Documentation

Everything in this deck is documented, and the source is public.

Start

reef.clawbits.aiArchitectureEgress allowlists in practice

Setup

Prepare a host

Agents

OpenClawHermes

Enterprise

Set up a teamBrowser access with CloudflareScopes inside an agentTerminal access

reef on GitHub · microsandbox on GitHub · MIT license

Appendix