fiberd

module

v0.4.0-rc.1 Latest Latest Go to latest Published: Nov 6, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Azure/fiberd

Links

Open Source Insights

README ¶

fiberd

The control plane issues a signed capacity grant once. The home verifies it, warms one template and creates fibers locally. It returns endpoints to callers and reports aggregate status.

Platforms often need many instances of the same workload, started on demand. The workload may be a container, an agent or a plain process. Each new instance usually boots, loads its code and fills its own memory, and often waits on a control plane first, even though it is a copy of one that already runs. fiberd creates those instances from one warm copy, fast and densely, inside whatever already places the workload, such as Kubernetes or Slurm. It is a reference implementation, not yet production-ready, and production-readiness.md lists what is missing.

What fiberd does

A template starts once and stays warm.
Each fiber is a cheap fork or snapshot restore of that template, so it starts in milliseconds.
An issuer grants a block of capacity once, as a signed grant.
The home checks the grant locally and mints fibers from it without calling back.

Why fiberd

fiberd works with the scheduler, not instead of it. Fast starts from a warm copy are not new either. Android's zygote forks warm processes, and Firecracker and Lambda SnapStart restore snapshots. fiberd's part is making that safe to run at scale.

Placement once, instances locally. The scheduler places a signed block of capacity once. The home creates instances inside it with no API write or scheduler call per instance, so the scheduler sees one placement instead of one object per instance.
Every instance stays checkable. Each fiber's fence ties it to its grant and to fiberd's epoch, so revocation and restarts reach every fiber. Each operation lands in a hash-chained audit log with signed checkpoints. A caller that misses gets a typed answer that says whether to back off or fall back.
One contract, any scheduler, any isolation. The same grant works on Kubernetes, Slurm or a bare host, and over plain processes, runc, gVisor, Hyperlight or Cloud Hypervisor.
Sessions move. A parked session can resume on another home, verified and sealed to its tenant. A home given a drain budget parks its sessions when it stops, rather than losing them.

The fastest path, proc and runc, shares the host kernel, so it suits trusted code. Untrusted code runs on gVisor, Hyperlight or Cloud Hypervisor, where a fiber is a snapshot restore.

fiberd verbs

Clone returns a fiber for a grant, anonymous or by session name.
Park saves a session and frees its fiber's memory.
Release ends a fiber.
Discard deletes a parked session.
Watch streams a summary of each grant.

protocol.md is the wire contract for all verbs.

Reading path

Read in this order, and look up any term in the glossary.

Quickstart to see it run.
Architecture for how it is designed.
Security for the trust boundaries.
The operator guides, which are Operating on Kubernetes, Networking, Resources and Production readiness.
The design docs for each module in depth.
The examples for fiberd in real environments.
Protocol for the wire contract, and Benchmarks for measured results.

Install

Each release has an archive per platform, named fiberd_<version>_<os>_<arch>.tar.gz, for linux or darwin on amd64 or arm64. The libfiberzygote archives hold the zygote library. Check the checksum and provenance before you unpack.

gh release download v0.1.0 -R Azure/fiberd -p fiberd_0.1.0_linux_amd64.tar.gz -p SHA256SUMS
shasum -a 256 --ignore-missing -c SHA256SUMS
gh attestation verify fiberd_0.1.0_linux_amd64.tar.gz -R Azure/fiberd
tar -xzf fiberd_0.1.0_linux_amd64.tar.gz
./fiberd -version

The release publishes three images, each with the same version tags.

ghcr.io/azure/fiberd holds fiberd, criu and the zygote library.
ghcr.io/azure/fiberd-runc adds the runc fiberd was built and tested against.
ghcr.io/azure/fiberd-gvisor adds the runsc fiberd was built and tested against.

The two variants also hold the empty mount points of a sandbox rootfs at /usr/share/fiberd/rootfs. A deployment on the runc or gVisor runtime builds on one of them and adds its workload.

gh attestation verify oci://ghcr.io/azure/fiberd:0.1.0 -R Azure/fiberd

Releases after v0.1.0 also publish the Python SDK to PyPI. Its sdist and wheels are release assets too, under the same SHA256SUMS and provenance.

pip install 'fiberd[client]'

Start

make build
make conform-stub   # the conformance suite on the in-memory runtime, on any OS
make conform-proc   # the same on real fibers, in the Linux dev container (hack/dev)

The quickstart walks through each call. To write your own template, read sdk/c/template/README.md for C or sdk/python/README.md for Python, and the zygote design.

Callers can use the Go client, Python client, or TypeScript client for Node.js.

Examples

Kubernetes is a core home. A grant Pod runs fiberd's own image with fiberd -home kubernetes. The controller that turns each CapacityGrant custom resource into a signed grant and one grant Pod is a separate project, fiberd-k8s-controller.
Slurm runs fiberd inside a job allocation.
Knative is an activator, the component that holds requests while a service scales from zero, here with fibers in Hyperlight micro-VMs.
Kata-shaped shim is a containerd shim, the plug-in that starts a Pod's containers. It has the shape of the Kata Containers shim without using Kata, and its containers are fibers.
Agent Substrate is a worker for a platform that starts, suspends and resumes actors in worker Pods. Its actors are fibers.

Contributing

CI runs the unit tests (make test) on linux/amd64 and macOS as a non-root user. The integration suites under tests/ and each example's tests/ build only with -tags integration and run as root in the dev container (make integration-tests). Run make test and make lint before sending a change.

make integration-tests and make linux-test rebuild the TypeScript client first when its dependencies are installed (npm ci --ignore-scripts --prefix sdk/typescript, Node.js 22.12 or later). Without them they leave out the TypeScript suite and say so.

The dev image

hack/dev/run.sh, and every make target that uses the dev container, pulls the image from ghcr.io/azure/fiberd-dev. The tag is a hash of docker/dev/Dockerfile and the files it copies, printed by hack/dev/image-tag.sh. The dev-image workflow publishes that tag when those files change on main.

When the tag is missing or the registry cannot be reached, hack/dev/run.sh builds the image locally. A change to those files therefore tests its own image. Set FIBERD_DEV_BUILD=1 to force a local build.

When the workflow fails, jobs keep working by building locally, which needs snapshot.debian.org. Fix the cause or wait out the outage, then re-run the failed jobs or start the workflow by hand. The workflow skips a tag that is already published, so refreshing what the image holds takes a change to one of those files.

License

Apache-2.0.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
grant/v1
cmd
audit-verify command Command audit-verify checks a home's audit spool.	Command audit-verify checks a home's audit spool.
fiberd command Command fiberd verifies signed grants offline, mints fibers under them through a runtime, and serves the grant protocol (api/grant/v1) over gRPC.	Command fiberd verifies signed grants offline, mints fibers under them through a runtime, and serves the grant protocol (api/grant/v1) over gRPC.
grant-issuer command Command grant-issuer is the reference issuer: it holds one signing key, mints CapacityGrant JWTs, and serves the OIDC discovery document and JWKS that homes verify against.	Command grant-issuer is the reference issuer: it holds one signing key, mints CapacityGrant JWTs, and serves the OIDC discovery document and JWKS that homes verify against.
zygotectl command Command zygotectl builds, pushes, pulls and inspects zygote artifacts.	Command zygotectl builds, pushes, pulls and inspects zygote artifacts.
examples
kubernetes module
hack
cloudhv/fakevmm command Command fakevmm stands in for cloud-hypervisor where there is no KVM, so fiberd's cloudhv backend, the host runtime and the conformance suite run in CI as hack/hyperlight/fakehelper lets the hyperlight backend run.	Command fakevmm stands in for cloud-hypervisor where there is no KVM, so fiberd's cloudhv backend, the host runtime and the conformance suite run in CI as hack/hyperlight/fakehelper lets the hyperlight backend run.
cloudhv/vmtemplate command Command vmtemplate is the reference template of the cloudhv backend: the workload the guest init runs in every micro-VM, and the fake VMM runs as its child without one.	Command vmtemplate is the reference template of the cloudhv backend: the workload the guest init runs in every micro-VM, and the fake VMM runs as its child without one.
conform/registry command Command registry serves an OCI registry for conformance runs.	Command registry serves an OCI registry for conformance runs.
fibctl command Command fibctl sends one line to a fiber's endpoint and prints the reply: the shell's way to talk to a reference-zygote fiber.	Command fibctl sends one line to a fiber's endpoint and prints the reply: the shell's way to talk to a reference-zygote fiber.
hyperlight/fakehelper command Command fakehelper runs hack/hyperlight/fakehelper/helper as a process: hack/hyperlight/PROTOCOL.md without a hypervisor, so fiberd's hyperlight backend, the host runtime and the conformance suite can run in the Linux dev container.	Command fakehelper runs hack/hyperlight/fakehelper/helper as a process: hack/hyperlight/PROTOCOL.md without a hypervisor, so fiberd's hyperlight backend, the host runtime and the conformance suite can run in the Linux dev container.
hyperlight/fakehelper/helper Package helper serves hack/hyperlight/PROTOCOL.md without a hypervisor, each fiber a goroutine and each park a JSON file.	Package helper serves hack/hyperlight/PROTOCOL.md without a hypervisor, each fiber a goroutine and each park a JSON file.
sessioncheck command Command sessioncheck is one session's round trip as a consumer sees it: mint a grant, Clone a named session, speak HTTP to the fiber over the endpoint Clone returned, Park it, Clone the same session again (a RESUME) and check the counter survived, then Release with discard.	Command sessioncheck is one session's round trip as a consumer sees it: mint a grant, Clone a named session, speak HTTP to the fiber over the endpoint Clone returned, Park it, Clone the same session again (a RESUME) and check the counter survived, then Release with discard.
storm command Command storm drives an overcommit storm against a fiberd home and reports whether the pressure ladder parked fibers before the kernel killed anything.	Command storm drives an overcommit storm against a fiberd home and reports whether the pressure ladder parked fibers before the kernel killed anything.
internal
cli Package cli is the plumbing fiberd's commands share.	Package cli is the plumbing fiberd's commands share.
pkg
artifact Package artifact packages a zygote as an OCI artifact and moves it through a registry, so every home that holds a grant for a template warms byte-identical zygote pages from one content-addressed source.	Package artifact packages a zygote as an OCI artifact and moves it through a registry, so every home that holds a grant for a template warms byte-identical zygote pages from one content-addressed source.
backend Package backend is the seam between fiberd's host runtime and a sandbox mechanism.	Package backend is the seam between fiberd's host runtime and a sandbox mechanism.
backend/cloudhv Package cloudhv is the Cloud Hypervisor backend: every fiber is a cloud-hypervisor process holding one micro-VM, restored from a snapshot of the warm guest.	Package cloudhv is the Cloud Hypervisor backend: every fiber is a cloud-hypervisor process holding one micro-VM, restored from a snapshot of the warm guest.
backend/gvisor Package gvisor is the gVisor backend: every fiber is its own runsc sandbox, restored from a checkpoint of the warm template sandbox, so a fiber has a sandbox kernel between it and the host and the tier is FIBER_SNAPSHOT.	Package gvisor is the gVisor backend: every fiber is its own runsc sandbox, restored from a checkpoint of the warm template sandbox, so a fiber has a sandbox kernel between it and the host and the tier is FIBER_SNAPSHOT.
backend/hyperlight Package hyperlight is the Hyperlight backend: every fiber is a Hyperlight micro-VM restored from a snapshot of the warm guest, held by a helper process that fiberd starts per grant and drives over the line protocol in hack/hyperlight/PROTOCOL.md.	Package hyperlight is the Hyperlight backend: every fiber is a Hyperlight micro-VM restored from a snapshot of the warm guest, held by a helper process that fiberd starts per grant and drives over the line protocol in hack/hyperlight/PROTOCOL.md.
backend/proc Package proc is the fork backend.	Package proc is the fork backend.
backend/runc Package runc is the proc backend with a launcher that runs the zygote as the init of an OCI container.	Package runc is the proc backend with a launcher that runs the zygote as the init of an OCI container.
core
core/coretest Package coretest holds helpers for tests of code built on pkg/core.	Package coretest holds helpers for tests of code built on pkg/core.
endpoint Package endpoint is how a fiber's address is written, chosen and dialled.	Package endpoint is how a fiber's address is written, chosen and dialled.
fiberd Package fiberd is fiberd as a library: the flags, the wiring of verifier, runtime, ledger, pressure ladder, admin socket and RPC server, and the fixed startup order (epoch++ -> reconcile -> open RPC).	Package fiberd is fiberd as a library: the flags, the wiring of verifier, runtime, ledger, pressure ladder, admin socket and RPC server, and the fixed startup order (epoch++ -> reconcile -> open RPC).
grant Package grant encodes CapacityGrant as a signed JWT and verifies it offline.	Package grant encodes CapacityGrant as a signed JWT and verifies it offline.
handoff Package handoff is fiberd side of connection handoff.	Package handoff is fiberd side of connection handoff.
home Package home defines the seam between the invariant core and the environment that holds a grant: a standalone host, a Kubernetes grant Pod, a Slurm allocation.	Package home defines the seam between the invariant core and the environment that holds a grant: a standalone host, a Kubernetes grant Pod, a Slurm allocation.
home/grantdir Package grantdir delivers grants to every file-fed home from a directory polled for *.jwt files.	Package grantdir delivers grants to every file-fed home from a directory polled for *.jwt files.
home/kubernetes Package kubernetes is fiberd's home in a Kubernetes grant Pod, where fiberd is the Pod's one container.	Package kubernetes is fiberd's home in a Kubernetes grant Pod, where fiberd is the Pod's one container.
home/kubernetes/fake Package fake serves the Kubernetes home's slice of the API from memory, for tests that need no API server.	Package fake serves the Kubernetes home's slice of the API from memory, for tests that need no API server.
home/standalone Package standalone is the home for a plain host: no scheduler, no kubelet.	Package standalone is the home for a plain host: no scheduler, no kubelet.
rpc Package rpc serves the grant protocol (api/grant/v1) over gRPC on top of a core.Core, and optionally exposes a thin JSON gateway.	Package rpc serves the grant protocol (api/grant/v1) over gRPC on top of a core.Core, and optionally exposes a thin JSON gateway.
runtime/host Package host is the runtime every sandbox mechanism plugs into.	Package host is the runtime every sandbox mechanism plugs into.
runtime/host/wsfs Package wsfs is the file layer of a fiber's workspace.	Package wsfs is the file layer of a fiber's workspace.
runtime/stub Package stub is an in-memory runtime for tests and for the conformance suite's first target.	Package stub is an in-memory runtime for tests and for the conformance suite's first target.
sys/caps Package caps narrows the capabilities of fiberd and of everything it starts, such as criu, the zygote and a backend's helpers.	Package caps narrows the capabilities of fiberd and of everything it starts, such as criu, the zygote and a backend's helpers.
sys/cgroup Package cgroup is a thin view of a delegated cgroup v2 subtree: create leaves with a memory ceiling and group OOM, open them for clone3, read what they charge, and kill them.	Package cgroup is a thin view of a delegated cgroup v2 subtree: create leaves with a memory ceiling and group OOM, open them for clone3, read what they charge, and kill them.
sys/criu Package criu wraps the criu command line for the two things fiberd needs: dump one fiber's process tree into an image directory, and restore it later into a cgroup leaf of the runtime's choosing.	Package criu wraps the criu command line for the two things fiberd needs: dump one fiber's process tree into an image directory, and restore it later into a cgroup leaf of the runtime's choosing.
sys/helper Package helper starts the programs fiberd hands privileged work to, such as criu, runc, runsc and ldd.	Package helper starts the programs fiberd hands privileged work to, such as criu, runc, runsc and ldd.
sys/mounts Package mounts prepares what a container mounts read-only before fiberd builds its runtime.	Package mounts prepares what a container mounts read-only before fiberd builds its runtime.
sys/netns Package netns runs small pieces of work inside another process's network namespace.	Package netns runs small pieces of work inside another process's network namespace.
tlsconf Package tlsconf builds the control plane's TLS configurations, for the fiberd's mutual-TLS server and for the callers that dial it.	Package tlsconf builds the control plane's TLS configurations, for the fiberd's mutual-TLS server and for the callers that dial it.
tlsconf/tlsconftest Package tlsconftest issues throwaway certificates for tests that need TLS or mutual TLS, in the spirit of net/http/httptest.	Package tlsconftest issues throwaway certificates for tests that need TLS or mutual TLS, in the spirit of net/http/httptest.
sdk
go/client Package client is the grant protocol from the caller's side: a client for Clone, Park, Release, Discard and Watch that turns the two miss outcomes into typed errors a consumer branches on.	Package client is the grant protocol from the caller's side: a client for Clone, Park, Release, Discard and Watch that turns the two miss outcomes into typed errors a consumer branches on.