Fenced

Fenced

The OS kernel for AI agents. Every agent runs fenced.

Fenced (formerly AgentOS) manages the execution around your agent code: it stores task state in PostgreSQL, places work on runtime pools, recovers after worker lease loss, and rejects writes from stale workers. Gateways authorize and meter tool and model calls against task budgets.

Use it when your agent tasks need to survive worker failures, coordinate through durable mailboxes, or run with explicit execution budgets.

Try locally · Recovery and fencing · Architecture · Current limits · 中文使用指南

Apache 2.0 · Source version: 1.4.0 · v1.2 public contract freeze

Try locally

Start with a dependency-free Python agent and the Runtime Interface conformance suite. You need Go 1.26.x and Python 3.11+. This trial needs no Docker, model account, API key, or framework installation.

Naming note: Fenced was previously named AgentOS. The repository, CLI binaries, SDK package names, Go module path, and protocol identifiers have all been renamed to Fenced / fenced. Historical documents and released artifacts may still reference the former name; see docs/NAMING.md for the complete migration map and compatibility notes.

git clone https://github.com/CloudEdgeCore/Fenced.git Fenced
cd Fenced

PowerShell:

$env:PYTHONPATH = "./sdk/python"
go run ./cmd/fenced-conformance -cmd "python examples/agents/python_remote/server.py --port 0" -timeout 30s

Bash / zsh:

PYTHONPATH=./sdk/python go run ./cmd/fenced-conformance -cmd "python3 examples/agents/python_remote/server.py --port 0" -timeout 30s

The command starts a local adapter, discovers its port, checks the protocol, and stops the adapter when finished. The first Go build downloads dependencies.

Expected output includes:

Adapter:  python-remote
Protocol: fenced.runtime.interface/v1
...
Fenced Compatible = PASS

What this checks: startup, idempotency, events, checkpoint/restore, result, stop, and capability denial at the Runtime Interface boundary.

Scope: the example uses an EchoAgent and in-memory checkpoints. This is a protocol smoke test; it does not exercise the PostgreSQL task kernel, real model calls, durable recovery, or sandbox isolation.

To run the complete local platform, follow the control-plane setup.

Recovery and fencing

When recovery retries a task after worker lease loss, it creates a replacement attempt with a higher fencing token. Calls carrying the expired identity are rejected before they can update durable task state.

Reproduce the takeover check with Go and a disposable PostgreSQL instance; no model or API key is needed. It deliberately expires a lease, invokes recovery, and verifies that:

1. The replacement receives a higher fencing token.
2. The old identity cannot heartbeat, commit a checkpoint, change phase, or read its assignment.
3. No stale checkpoint reaches PostgreSQL.

The check uses real storage and the Runtime Control service. It injects lease expiry directly; it does not kill a deployed worker process.

For a broader deterministic workload, the research workflow takeover report describes worker loss and replacement across runtime pools, with commands and the boundaries of that experiment.

How it works

flowchart LR
    A["Your agent + Runtime Interface adapter"] --> B["Control API"]
    B --> C["PostgreSQL: Task / Run / Attempt"]
    C --> D["Admission: policy + budgets"]
    D --> E["Scheduler + recovery"]
    E --> F["Worker: fenced lease"]
    F --> G["Tool / Model / Memory gateways"]
    G --> C
    F --> H["Checkpoint + result"]
    H --> C

Publish an immutable agent version, submit a task, and let admission and the scheduler select a runtime pool. Workers execute through Runtime Protocol v1; gateways enforce authorization and usage accounting on calls routed through them. Replacement workers can resume compatible checkpoints.

See the architecture and framework integration guide for the full design.

What is available

Framework adapters include LangGraph, AutoGen, CrewAI, OpenAI Agents, and custom agents. Start with the ecosystem guide; use the conformance suite to check an adapter's Runtime Interface compatibility.

For services, supply a published spec.agentVersionRef and spec.workloadSpec (fenced service create -spec task-spec.json), and apply migration 000037. Each replica consumes a real worker slot and retains Task budgets and timeouts. See the service guide.

Current limits

• CLI-first operation. The web workbench is an internal, loopback-only preview; a production administration console and managed hosting are pending.
• Infrastructure you operate. The full platform uses PostgreSQL and NATS. Production paths require configured HTTPS/OIDC and SPIFFE mTLS identities; model, tool, embedding, and secret services need their own configuration.
• Fencing protects ownership. It rejects stale kernel operations. Physical isolation depends on the runtime, such as Wasmtime or OCI/gVisor; the reference provider is development infrastructure.
• Cancellation is cooperative; attempts are non-preemptible. Workers must acknowledge cancellation. Checkpoint recovery requires compatible agent versions, runtime ABIs, and state schemas.
• Resource controls use different mechanisms. Gateway budgets, scheduling capacity, and sandbox limits have different enforcement points. Calls that bypass the gateways are outside their usage accounting.
• Frozen contracts have implementation boundaries. Syscall ABI 1.0.0 defines 21 calls across eight groups. Production gateway entry points currently register Tool, Model, Memory, and IPC services; unified Syscall and Effect endpoints are not yet wired into those entry points.

See the feature status matrix and production setup before deployment.

Evidence and compatibility

Reproducible raw 72h/7d production soak evidence is not yet published. The existing soak report does not include the raw logs and run metadata needed to substantiate those duration claims.

The v1.2 contract freeze documents stable Runtime, Gateway, Control API, Service, IPC, Effect, and Syscall contracts. Breaking changes require a new contract version. Legacy v1alpha1 compatibility will not close before 2027-02-17; see the compatibility policy.

Documentation

• AGENTS.md and the Makefile: the repository map, the verification ladder, and the day-to-day task runner (make help).
• User guide / 中文使用指南: manifests, tasks, workflows, services, and CLI usage.
• Development reference: full local setup, observability, validation commands, and release verification.
• Frameworks and runtimes: adapters, providers, SDKs, and reference applications.
• Helm deployment: production HTTPS, OIDC, and Secret configuration.
• Naming and migration and compatibility: the AgentOS → Fenced rename map, what a pre-rename deployment can keep doing, and what must be migrated.
• Changelog and GitHub Releases: source changes and published assets.

Try it and share feedback

Run the local trial and open an issue with the first step that blocks you: your OS, the command, and the error output. If you already run agent workloads, describe the failure or budget-control problem you would want Fenced to handle.