fiber

README

fiber

Define agents, run them durably, and stream answers across your tools.

Download · Report Bug · Go Docs

     

Real output from the offline example. The model and destination services are simulated.

Status

fiber is v0 alpha software. It is pre-1.0 and not recommended for production.

Interfaces are still moving and may change between minor versions, and a minor release may require code changes on your side.

What that means concretely today:

• Works and is tested. The single-binary deployment (in-memory bus, ledger and registry), the topic and delivery model, durable runs with replay, the Connect and SSE transports, and the Slack, GitHub, Jira, cron and webhook connectors.
• New and lightly exercised. Postgres persistence for agent specs, runs and knowledge (FIBER_POSTGRES_URL), the knowledge layer, the built-in author agent, and history compaction. The Postgres backends pass the same suites as their in-memory counterparts in CI's integration job and in make e2e; none of it has seen production load.

See Limitations for the full list.

fiber is an agent platform and a low-latency pub/sub bus. Define an agent with a spec, tag it from Slack, GitHub, Jira or a schedule, and its events stream to any subscriber while being delivered to any destination you name.

Where a tag is raised and where its answer lands are independent. A GitHub request can stream into Slack while a webhook receives only its completion event. Each run pins an agent revision, so retries use the same definition.

Features

• Agents are documents. Create one by submitting a spec. No redeploy, no code, no restart.
• Subscribe once. agent:docs-bot receives current and future runs of that agent through one topic.
• Route by event. Send one run to multiple destinations; each chooses text, citations, lifecycle events, or all of them.
• Connectors act, not just talk. The Actor face contributes native verbs (transition a Jira ticket, request a review) as agent tools, sandboxed by NGAC, each emitting an auditable action.taken event.
• Persistent when configured. Postgres keeps definitions, runs, and knowledge across restarts; Redis carries the event stream. In-memory backends keep local development simple.
• Revisions are pinned per run. A run accepted under revision 6 executes as revision 6 forever, even after a revise, because replay demands it.
• Citations are first-class events, carrying the exact quoted source and resolvable provenance.
• Every run reports what it spent. Each model call is a usage.call event (tokens, cache share, model, context window, and cost where saige's price catalog has the model), and the run's total, delegations included and each call counted once, is on its terminal event and GetRun.
• A run can wait for a person. A tool listed in a spec's approvals, or the built-in ask_person tool, parks the run on a question (approve or deny a call, pick an option, or reply). The run frees its worker, survives restarts, publishes the question on lifecycle.parked, and resumes with the first answer (InvokeService.Answer, fiber answer). An unanswered question takes its default when it expires.
• One contract, three transports. Connect serves gRPC, gRPC-Web and HTTP/JSON, plus resumable SSE for browsers.

Installation

Prerequisites

Path	Requirements
Prebuilt CLI	macOS or Linux
Build or run examples	Go version from go.mod, Git
Persistent local stack	Docker with Compose v2, Make
Real model inference	Provider credentials, a local Ollama service, or an OpenAI-compatible server

Script (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/urmzd/fiber/main/install.sh | sh

Go

go install github.com/urmzd/fiber/cmd/fiber@latest

Library

go get github.com/urmzd/fiber

Quick Start

Run the complete offline example from a checkout. After Go downloads its dependencies, the demo needs no API key or external services:

git clone https://github.com/urmzd/fiber.git
cd fiber
go run ./examples/local

It creates an agent, revises it, tags it from a simulated GitHub trigger with delivery routed to Slack and a webhook, shows a third party listening to the agent's topic, and demonstrates that a replayed run does not pay for the model twice.

Persistent local stack

From the same checkout:

make up
make e2e

Compose starts Postgres, Redis, and fiber at http://localhost:8383. The end-to-end check creates and revises an offline agent, runs it, restarts fiber, checks persistence, and verifies a citation from indexed documentation. It does not call a paid model. Run make down to stop the stack and keep its data.

Use a model

With the CLI installed, run the server in one terminal:

export ANTHROPIC_API_KEY="your-api-key"
export FIBER_TOKEN="local-development-token"
fiber serve

In another terminal, use the same token and a model your provider account supports:

export FIBER_TOKEN="local-development-token"

cat > docs-bot.json <<'JSON'
{
  "name": "docs-bot",
  "description": "Answers questions about the deploy pipeline",
  "provider": "anthropic",
  "model": "claude-haiku-5-5",
  "system_prompt": "You answer questions about the deploy pipeline. Cite your sources."
}
JSON

fiber agent create -f docs-bot.json
fiber tag docs-bot "how does a release get out the door?"

To use OpenAI, or any server that speaks its Chat Completions API (vLLM, LM Studio, llama.cpp, OpenRouter, Groq), set "provider": "openai" and the model that server hosts. For a local server, point fiber at it instead of setting a key:

export OPENAI_BASE_URL="http://localhost:8000/v1"   # omit for OpenAI itself
export OPENAI_API_KEY="your-api-key"                # optional for a local server

Models saige's catalog does not know report their token usage and no cost.

An agent can name fallback models, tried in order when a call to its primary model fails with an error another model could fix (an outage, a rate limit, a refused credential):

"fallbacks": [
  {"provider": "openai", "model": "gpt-5"},
  {"provider": "ollama", "model": "llama4"}
]

Each fallback names a provider the deployment knows and a model, none repeats the primary or another fallback, and there are at most four. By default any error another model could fix falls through. "fallback_on" narrows that to named classes: unavailable (an outage), rate_limit, transient (a timeout or reset connection, and also a rate limit or outage), auth, context_length and content_filter, or any alone, which is the default. For example "fallback_on": ["rate_limit", "unavailable"]. It is a set, and naming it without fallbacks is refused. Whatever it names, an invalid request, a stopped run or an exhausted budget does not fall through, and a stream that already produced output is not replayed on another model. Every fallback is built with the agent, so one whose provider is not configured (say, OPENAI_API_KEY is unset) fails the build like the primary would. Each call is priced on the rate card of the model that answered it. Order is part of the revision: reordering fallbacks is an edit. A spec without fallbacks hashes exactly as it did before they existed.

An agent can be granted an MCP provider's tools as one name: "tools": ["mcp:urmzd"] grants the tools an admin accepted on the provider urmzd as read, and "mcp:urmzd:write" its write tools as well. Read only is the default, so leaving the class off can only grant less, and the class is checked again on every call. The model is shown each member tool (urmzd__create_issue), never the group, and approvals name members: "approvals": ["urmzd__create_issue"]. The group is expanded for the run's tenant each time a run builds the agent, so a newly accepted tool reaches the agent without a new revision; tools that are not accepted, or that changed since, are never offered. fiber serve expands groups against its tool provider store (Postgres when FIBER_POSTGRES_URL is set) and resolves env:NAME credential references from its environment. A host embedding pkg/runtime does the same with runtime.WithToolGroupSource and an mcptools.Grants; one embedding pkg/agentrt alone supplies groups with agentrt.WithToolGroups or from its tool catalog.

After configuring the GitHub and webhook connectors, route the same agent's answer to multiple destinations. Replace the example addresses with yours:

fiber tag docs-bot "how does a release get out the door?" \
  --deliver 'github://urmzd/fiber/issues/42|delta' \
  --deliver 'webhook://acme/deploys|lifecycle.completed'

Watch the bus. This subscriber invoked nothing and still sees every run:

fiber listen agent:docs-bot
fiber listen agent --kinds lifecycle.completed --format json | jq

Examples

Example	What it demonstrates
local	Offline agent revisions, selective delivery, citations, and replay
compose	Postgres persistence, Redis streaming, and indexed documentation

See the example index for more.

Commands

Command	Purpose
fiber serve	Run the core: API, SSE, webhooks, bus, router, worker
fiber work	Run an execution node with no inbound API
fiber agent	Create, revise, get, list, history, delete
fiber tag	Tag an agent and stream its answer
fiber listen	Subscribe to a topic and print events
fiber stop	Ask a run to stop; it keeps what it had said and ends with lifecycle.stopped
fiber answer	Answer the question a parked run is waiting on (--approve, --deny, --choose, --reply)
fiber index	Index files into a named knowledge source in Postgres
fiber version	Version, commit, build date
fiber update	Self-update from GitHub releases

Every command takes --format text|json. Results go to stdout, diagnostics to stderr, so --format json output pipes cleanly into jq even while the same process logs a reconnect.

Documentation

Document	Covers
docs/architecture/overview.md	Topics, connector faces, N:M delivery, revision pinning, package DAG, limitations
AGENTS.md	AI-facing conventions, commands, rules, extension guide
examples/README.md	Runnable example index
CONTRIBUTING.md	Development workflow and commit convention
SECURITY.md	Security boundaries and reporting

API reference: pkg.go.dev/github.com/urmzd/fiber

Architecture

fiber builds on three libraries and adds addressing, distribution and the control plane:

Concern	Owner
Agent loop, typed deltas, RAG, citations	saige
Durability, replay, per-run journal	anchor
Sandboxed execution nodes, NGAC	playscape
Topics, bus, routing, connectors, specs	fiber

See the architecture guide for delivery, authorization, and replay guarantees. warp adds product workflows and a web surface on top of the platform.

Configuration

Variable	Purpose
FIBER_TOKEN	Shared development credential for the server and CLI
FIBER_TENANT	Authorization scope; defaults to default
FIBER_POSTGRES_URL	Persist the registry, run ledger, queue, and knowledge
FIBER_REDIS_URL	Use Redis Streams for the event bus
ANTHROPIC_API_KEY	Authenticate the Anthropic provider
OPENAI_API_KEY	Authenticate the openai provider; optional with OPENAI_BASE_URL
OPENAI_BASE_URL	Point the openai provider at an OpenAI-compatible server
FIBER_EMBEDDINGS_URL, _MODEL, _KEY, _DIMENSIONS	Configure an OpenAI-compatible embeddings endpoint
FIBER_PROVIDERS	Default for serve --providers: a JSON file of model endpoints and MCP tool providers
FIBER_AUTHOR_PROVIDER, FIBER_AUTHOR_MODEL	Select the built-in author agent's model
FIBER_COMPACT_TOKENS	Enable history compaction at a token threshold; off by default
FIBER_COMPACT_KEEP_TURNS	Recent tool-calling turns a compaction keeps verbatim; defaults to saige's
FIBER_COMPACT_ON_REQUEST	Let a host compact a running turn with POST /v1/runs/{id}/compact; off by default

Without an embeddings endpoint, indexing uses a local hashing embedder for offline development. Use the same embedding settings for serve and index.

Compose sets FIBER_TOKEN=fiber-dev-token by default. Use that value when connecting from a host CLI. Connector setup is covered in the GitHub and Slack guides.

Extending fiber

Common cases need no Go. fiber serve --providers providers.json declares OpenAI-compatible model endpoints, each selectable by name as a spec's provider, and MCP tool providers with the tools the deployment accepts from each, pinned by schema hash. Keys and credentials are named, never written: api_key_env is the variable that holds a model key, and credential_ref is env:NAME.

{
  "models": [
    {"name": "fireworks", "base_url": "https://api.fireworks.ai/inference/v1", "api_key_env": "FIREWORKS_API_KEY"},
    {"name": "vllm", "base_url": "http://vllm.internal:8000/v1", "api_key_env": "VLLM_API_KEY"}
  ],
  "tool_providers": [
    {"name": "issues", "transport": "http", "endpoint": "https://mcp.example.com/mcp",
     "credential_ref": "env:ISSUES_TOKEN",
     "tools": [{"name": "search", "schema_hash": "4f1c…", "class": "read"},
               {"name": "close_issue", "schema_hash": "9b07…", "class": "write"}]}
  ]
}

A declared tool is accepted only while the server's schema for it matches schema_hash, and its description may not change once accepted. Anything the server adds or changes stays pending, so a restart never accepts what the file does not declare. At startup serve logs every pending tool with its schema_hash; review it, then copy the hash into the file to accept it. A server that cannot be reached at startup is logged and its tools are unavailable to runs.

Anything else is a few lines of Go in your own binary. fiberapp.Main runs the same server and CLI as fiber, with options to register model providers, tool sources, connectors and MCP tool providers. examples/downstream is a complete one:

os.Exit(fiberapp.Main(fiberapp.Version{Version: "v1"},
    fiberapp.WithModelProvider("house", houseProvider),
    fiberapp.WithTools(runbookTool{}),
))

Upgrading

Run ids changed in this release. A run id is now derived from the tenant and the tag id together, so every run gets a different id than it had before.

• Drain before upgrading. Stop accepting tags and let in-flight runs finish on the old version. A durable replay recomputes the run id from the tag, so a run accepted by the old version and resumed by the new one is looked up under an id it was never stored under. Do not run old and new workers against the same ledger.
• Old redeliveries start new runs. A webhook redelivered across the upgrade no longer deduplicates against the run its first delivery created, because that run is stored under its old id.
• Upgrade clients for the stopped status. GetRun can now report RUN_STATUS_STOPPED (6) for a run that was asked to stop. A client generated before this release decodes it as an unknown enum value, so a poller waiting for completed or failed never sees a stopped run end. Regenerate or upgrade clients; until then, treat an unknown status as terminal or watch for lifecycle.stopped on the run's stream.
• Stored run ids are stale. Anything that saved a run id from before the upgrade (a link, a dashboard, a surface message) will not resolve it afterwards.

Limitations

• Event streaming uses the in-memory bus or Redis independently of the Postgres run store.
• The registry, run ledger and run queue are in memory unless FIBER_POSTGRES_URL is set. On Postgres they survive a restart, but anchor's pgqueue has no DeltaLog, so the per-run journal is not written; the bus still carries every event.
• playscape's queue is at-most-once in beta, so durability comes from anchor rather than from playscape.
• Citations are derived from RAG context blocks. saige's CitationDelta, which reports what a model or tool cited, is not translated into events yet.
• The bus is at-least-once with no consumer groups. If durable competing consumers become a requirement, NATS JetStream behind the Bus interface is a better answer than growing a broker here.
• Agent specs load from JSON, not YAML.
• Stopping a run is the HTTP route POST /v1/runs/{id}/stop, not an RPC; GetRun reports the result as RUN_STATUS_STOPPED. A stop is recorded in the run ledger before it is announced on the bus, so once it is acknowledged the run ends stopped unless its turn had already returned its answer. A route that selects only lifecycle.completed is not told about a stop.
• Compacting a running turn on request is the HTTP route POST /v1/runs/{id}/compact, not an RPC. The request is not recorded: it reaches only the attempt running when it is made, before that turn's next model call. See Compacting a run on request.
• There is no API or CLI command to register MCP tool providers or accept their tools yet; a deployment declares them in serve --providers FILE (or fiberapp.WithToolProvider), or an admin writes them to the tool provider store (pkg/toolprovider). A group grant that cannot be expanded (no such provider for the tenant, the server unreachable, nothing the grant's class admits) is dropped like a single unavailable tool: the run continues without it, the model is told it is unavailable, the operator is logged why, and Runner.Unavailable lists it. agentrt.WithStrictTools fails the build with agentrt.ErrNoSuchToolGroup instead.
• A granted tool this deployment cannot resolve (no connector contributes it, or an MCP tool is held back) is dropped rather than failing the run. The model is told it is unavailable and the server logs a warning naming the tool and the reason; agentrt.WithStrictTools restores the old refusal.
• Tool events carry the call's arguments, capped at 8 KiB; scrub sensitive ones with agentrt.WithToolArguments.
• A parked run waits on a person through the run ledger. An answer or a stop wakes it at once; an expired question is noticed by the worker's janitor poll (30 seconds by default), so its default applies up to that late. The requester cannot approve their own calls unless the spec sets self_approval, and approvers/answerers restrict who may answer. A tool implementing agentrt.Approving decides per call whether it needs approval and may name that call's approvers, which then replace the spec's. A host Delegator that blocks on a child run holds a worker and can exhaust them; runtime.WithChildRuns parks the parent on the child instead. Approvals inside an in-turn sub-task (a tag_<agent> call without child runs or a Delegator) are refused, not asked. See Parking a run on a person.
• Cost is reported only for models saige's price catalog prices, in integer micro-units with the catalog's as_of; anything else reports tokens and no cost. Usage is delivered only to routes that select usage. A turn that crashes mid-call is on the bus but not in the run's total. In-turn delegation is one level deep (a sub-task holds no spawn grant), and a host that runs delegations as runs of their own rolls them up with runtime.ReportChildUsage. See Usage.

Reproduce the Screenshot

Install teasr, then run from this checkout:

go run ./examples/local
teasr run --config teasr.toml

The first run warms Go's build cache. The capture runs the real demo and writes showcase/durable-replay.png.

License

Apache 2.0. See LICENSE.