Share inputs and compose a local image
From the project documentation.
A workspace layer shares signed APK inputs and complete SDK archives. Each machine composes those inputs on its own compatible Corb base. The resulting checkpoint belongs to that exact base and stays local. A different base needs an explicit build or pull, even when the shared inputs stay unchanged.
Producer
Install ORAS 1.3.5 on PATH for registry transfers.
Corb checks the version and never installs it. Choose a coherent local
Corb base with [vm].image in personal or workspace
settings. A base must pass package coherence and all seven production
image gates. Older images without the coherence report need a new base
build or a separately distributed base.
Initial composition runs only on native Linux x86_64
with QEMU. The recipient base must match the locked Alpine branch, even
for packages = []. Other valid target tables stay in the
lockfile without execution.
Put the recipe in the selected workspace's corb.toml,
outside all hosted mounts. For example:
Then run:
corb image pin --workspace tools
corb image layer build --workspace tools
corb image layer push registry.example/team/tools:v1 --workspace toolsPin explicitly refreshes signed Alpine main/community indexes and
resolves exact package identities. It gathers dependencies without using
the producer's installed database, then separately simulates the
requested install on the selected base. It authenticates every archive
before caching it. Pin executes no package scripts or custom commands.
It writes the selected corb.sum target last and clears its
old artifact binding. Other valid architecture targets and an existing
lockfile symlink stay intact.
Build uses those exact cached inputs. It runs a real signed APK transaction and copies complete SDK trees. The solver may retain compatible providers already on the base. It cannot change existing package identities or fetch an unbundled alternative.
The shared candidate closure retains archives that the producer already supplies. A recipient can need those same archives when its installed providers differ. The same Alpine branch does not guarantee compatibility. Conflicting providers or required base changes fail explicitly.
Corb displays runtime directories, hosts and ordered unpinned root commands before executing them. The builder closes before a separate checkpoint verifier boots. All seven gates and composition coherence must pass.
Push needs that verified local composition, but publishes only the
reusable input graph. It writes the immutable artifact URI into the
selected lock target after publication succeeds. It starts no VM and
changes no current generation pointer. Commit the workspace definition
and corb.sum to share them. Keep personal
trusted.json private. None of these image commands accepts
normal-run trust.
Recipient
Review the shared definition, pins and artifact digest, then run:
Pull reads the locked digest. It verifies the complete input graph
and composes on the recipient's locally selected base. It never
refreshes pins or changes corb.sum to fit a different base.
A complete valid current composition for the exact base is a no-op
without ORAS or VM work. A cached complete graph needs no registry or
APK CDN for composition, but custom commands and strict HTTPS image
gates retain their declared network needs. Initial verification is not
promised to work offline.
Normal run validates local inputs, base assets, generation metadata and checkpoint before reading credentials or creating a VM. It refuses a changed backing path before the SDK can rebase a checkpoint. It never fetches a registry, repins or builds implicitly. Missing state gives a build or pull hint. Dry-run and explain need no local generation.
SDK inputs and runtime directories
Use packages = [] for an SDK-only recipe. Pin then skips
all APK indexes and installer work. The payload schema requires an
exact HTTPS URL, digest, target architecture and dedicated destination.
Archive redirects must stay on declared build-hosts. A
digest fixes bytes. Review of the source establishes publisher
trust.
Corb rejects links, traversal, duplicates, special nodes and expansion beyond the documented bounds. It copies the complete tree with root ownership and immutable readable modes. It preserves executable bits. Every SDK PATH entry must remain inside its destination and preserve the security tools and forbidden-name policy.
For Go, declare the SDK bin directory in
path. Put GOCACHE, GOMODCACHE,
GOPATH and GOBIN in separate writable
workspace directories. Set GOTOOLCHAIN=local when the
locked SDK must supply the compiler.
Runtime directories name approved paths below /run or
/var/log, modes and guest account names. Corb checks the
accounts and every path component again before Pi starts on each resume.
It creates or fixes only the named directory, without changing children
recursively.
A mismatch fails and closes the session. The plan launches no service. There is no startup script, supervisor or automatic packaged-service launch. Ordered root build commands can install other toolchains, but cannot alter protected files or add/change APK identities. Services must be stopped before checkpointing. The checkpoint caches disk bytes, not running processes.
For Alpine Redis packages that use the ordinary packaged paths, declare both transient directories:
[[image.layer.runtime-dir]]
path = "/run/redis"
mode = "0755"
owner = "redis"
group = "redis"
[[image.layer.runtime-dir]]
path = "/var/log/redis"
mode = "0755"
owner = "redis"
group = "redis"Corb resolves the actual Redis account numbers after package
installation. Keep /var/lib/redis and
/etc/redis.conf as the package installs them. The
declarations restore directories before an explicit
redis-server /etc/redis.conf launch. The acceptance check
launches Redis through production dropcap from the root
builder or validated preparation context. They do not start Redis when a
session boots. Keep the packaged daemonization choice and stop the owned
service with ordinary Redis shutdown before checkpoint creation.
The ordinary agent runs as uid 1000 and cannot change to the Redis
account through dropcap. Corb provides no public root
service launcher.
Separate base distribution
Base artifacts are independent of input artifacts:
corb image verify private:base
corb image push registry.example/team/base:v1 --image private:base
corb image pull registry.example/team/base@sha256:DIGEST --tag private:receivedReplace DIGEST with the full printed digest. A base push
verifies the local image, preserves exact raw SDK asset bytes and prints
its immutable reference. A base pull validates the graph, asset hashes
and recomputed SDK build ID before import, then repeats production
verification. An existing exact object can have different harmless
manifest formatting, filenames or local build metadata. Its normalized
architecture, distro and Alpine release projection must agree with the
artifact.
An inconsistent existing object is an error. Without
--tag, pull imports untagged and prints its build ID and
directory. With --tag, it updates only that requested ref
after verification. SDK errors after a ref write can leave that
requested ref updated. Inspect the reported state before retrying. No
implicit version alias, workspace pin or layer pointer changes
occur.
An input pull does not fetch a base artifact. The recipient can compose on a different compatible base. Base graphs contain raw assets and the portable SDK projection. They contain no local checkpoint or source path.
corb image ls --json provides version-1 JSON for local
SDK refs and known workspace composition records. The SDK inventory
lists refs. It does not enumerate every untagged object. Recorded
composition status is not a substitute for run's full validation.
Listing is read-only and needs neither a VM nor network.
corb image verify [SELECTOR] uses the existing default when
omitted and never tags or repairs an image.
Registry and local-state limits
Push destinations require an explicit registry, repository and tag.
Pull identities require an immutable digest and never resolve a tag as
the expected identity. Both transports use verified HTTPS for localhost
registries too. ORAS 1.3.5 otherwise defaults localhost to HTTP, so Corb
passes explicit false-valued plain-http options.
Corb never enables plain HTTP or insecure TLS. Use
--registry-config FILE and --ca-file FILE when
needed. Otherwise standard ORAS credentials apply. Registry token
realms, redirects and host credential helpers are trusted transport
participants. This is not guest hostname confinement or independent
publisher authentication. These host settings never enter guest inputs
or shared artifact bytes.
Corb redacts URL userinfo, queries and fragments in ORAS error diagnostics before retaining their bounded output tails.
The acceptance fixture uses the official Distribution 3.1.2 binary with its immutable archive and executable hashes. Its release page provides the primary source.
The fixture creates its own CA, HTTPS endpoints, credentials and private storage on loopback ports. It uses a private registry config for every external ORAS transfer. Its small HTTPS proxy records methods, paths, status codes and authentication results without credentials or upload tokens.
Official access logging is disabled. The fixture also scrubs captured registry diagnostics and privately tracks dynamic upload-state markers. This fixture is test code. Corb does not provide a registry service.
Local state uses private directories, immutable verified cache
objects and one exclusive writer lock per workspace. A live or uncertain
owner fails. Corb recovers a lock only when its recorded local owner is
provably dead, never because of age. Completed generations stay under
CORB_STATE_DIR/layers/<workspace>/<arch>/bases/<base-id>/generations/<uuid>.
current.json changes last after candidate verification.
Each session receives a separate temporary SDK overlay. Changing a base
creates another cache while reusing the same authenticated input bytes.
There is no automatic generation or artifact garbage collection.
Registry writes, lockfile replacement and local pointer publication cannot form one atomic transaction. A failed late step can leave verified cache blobs, an unused completed generation or remote data. Corb reports the completed or uncertain stage and preserves the previous authoritative file where publication has not completed. It removes only its own temporary children. Repeated identical input pushes have the same manifest digest.
Moving a remote tag does not change an existing digest lock. Corb revalidates complete cached objects and refuses corrupt content without replacing it silently. If remote publication succeeds but lock replacement fails, the old lock remains authoritative. If composition fails after download, the previous current generation remains available.
The validation report separates local-layout evidence from measured remote HTTPS and packaged-service results.