Distribution — bundles, tamias, the provider boundary
A bundle is a manifest (tamias.yaml / .yml / .toml) plus a payload of workflows, .node.yml, .driver.yml and .field.yml files — the peregrin-bundle content type. Distribution itself lives in tamias: refs, transport, the install store, the fetch cache, deploy, and service lifecycle are all tamias verbs. Peregrin ships only the provider — tamias-driver-peregrin — which turns a bundle's provider: block into an operator node config and lets tamias render its service units.
The old peregrin install/remove/list/info/update/pin/verify/cache/ bundle verbs are gone — run them via tamias. The hidden peregrin provision {install,deploy,uninstall} commands remain as the provider entrypoints tamias shells out to.
Ref grammar
tamias install ./docs-deploy # filepath — dev loop
tamias install git:9aia/peregrin/libraries/docs-deploy # shorthand (github), default branch
tamias install git:github.com/9aia/peregrin//libraries/docs-deploy#v0.2.0
tamias install git:[email protected]:9aia/peregrin//libraries/docs-deploy#main
tamias install git:https://gitlab.com/grp/sub/repo//dir # any git url
tamias install https://9aia.com/bundles/docs-deploy-0.1.tgz # non-git tarballgit:<url>[//<subdir>][#<ref>]—//(go-getter convention) splits the repo path from the in-repo path; it's required for nested groups because barea/b/c/dis ambiguous.#refis a branch, tag or sha — the git ref is the version pin; the resolved commit sha is recorded regardless.- Without
//, a two-segment prefix is the repo and the remainder is the in-repo path — sogit:9aia/peregrin/libraries/docs-deployclonesgithub.com/9aia/peregrinand takeslibraries/docs-deployfrom it. This rule only applies to shorthand paths: anything containing://, scp-stylehost:path(git@…:), or an explicit local path (/x,~/x,./x) parses whole. - Shorthand —
org/repodefaults togithub.com;host/org/repobecomeshttps://host/org/repo.git@…,ssh://,file://and local paths pass through. ./path,/path,~/path,nested/path→source-fs. A directory copies its payload (.git/excluded); a.tgz/.tar.gz/.tarfile unpacks.http(s)://….tgz|.tar.gz→source-http, with an optional#sha256:<hex>(or#sha256=<hex>) digest pin verified on fetch.cf:refs hit the Cloudflare registry source.
Store + fetch cache (tamias)
- Install store —
<name>@<version-or-sha>/under~/.local/share/tamias/holds unpacked packages; each entry records the source ref, resolved sha, and payload digest. - Fetch cache — content-addressed
~/.cache/tamias/fetch/<key>/(git-<sha>for git,sha256-<hex>for content digests). Install is two-phase fetch→unpack: a warm cache makes repeat installs and air-gapped nodes free — a ref whose pin is already known skips the transport entirely on a cache hit. tamias remove <name>drops only the store entry; the cache evicts by age ortamias cache clean --all, never byremove.tamias verify <name>recomputes the payload digest and fails on mismatch;tamias doctorruns store/cache/registry/content-type diagnostics.
include: composition
A manifest may declare include: […] — base bundles whose payloads deep-merge under the local one. Entries are installed store names (name or name@version) or source refs (installed on demand). Semantics come from the ported loader: local wins, dicts merge per-key, arrays concatenate local-first, and node id collisions dedupe keeping the local definition — so an overlay that redefines a node can't double-fire it. Earlier include: entries outrank later ones. Conflicting .yaml/.yml/.json files merge document-wise; every other conflict resolves whole-file.
Tamias verbs (the ones that replaced peregrin …)
tamias install <ref> # fetch → store (+ alias); dispatches the
# content-type driver's install verb
tamias add|update <name> # update re-resolves the recorded source ref
tamias remove <name> # drop store entry; cache untouched
tamias list # installed packages, refs, digests
tamias info <name> # manifest, source ref, resolved sha, size
tamias pin <name> <ref> # retarget the recorded ref
tamias verify <name> # digest-check store contents vs recorded sha
tamias cache clean [--all] # evict fetch cache
tamias deploy <name> # render provider.services[] units + run the
# kind driver's deploy verb
tamias service enable|disable|status|logs # unit lifecycle
tamias doctor # host diagnostics
tamias bundle pack <dir> # authoring — dir + manifest → .tgzThe peregrin-bundle provider
A bundle opts into the declarative runtime by declaring type: peregrin-bundle (routed to tamias-driver-peregrin) plus a provider: block in tamias.yaml:
type: peregrin-bundle
provider:
name: peregrin # SHARED identity — see below
services:
- name: campaign # rendered as <provider>-<service>
exec: >-
~/.local/bin/peregrin campaign serve ~/.config/peregrin/serve
--listen 127.0.0.1:29173 --path /hook
--history-dir ~/.local/share/peregrin/serve-history
--queue-store-dir ~/.local/share/peregrin/serve-queues
env_file: "~/.config/peregrin/env"
workdir: "~"
restart: on-failure
ingress:
- public_url: https://ci.example.com
listen: 127.0.0.1:29173
path: /hook
hooks:
- forge: github
repo: 9aia/peregrin
events: [push]
verbs: [run, logs]- Shared provider identity (T8-7). Every
peregrin-bundledeclaresprovider.name: peregrin, so all theircampaignservices render one unit —peregrin-campaign.service— whoseExecStartiscampaign serve ~/.config/peregrin/serve, a directory the deploy driver fills with one generated node config per installed bundle.campaign servehosts them all on ONE webhook listener (demux byrepository.full_name). Shared-unit services MUST keepexecidentical across bundles — last deploy wins the unit file. tamias install <ref>fetches + stores the package and dispatches the driver'sinstallverb — a no-op forperegrin-bundle(the node config is generated bydeploy, which sees the stable store dir; install only sees the evictable fetch cache).tamias deploy <name>dispatches the driver'sdeployverb —tamias-driver-peregrinregenerates~/.config/peregrin/<name>.yamlas the operator node config:include:of the bundle'smain.yaml, agithub-webhookingress node built from the manifest'sprovider.ingress[].hooks(forge: githubonly;secret_env=PEREGRIN_WH_<OWNER>_<REPO>),config.public_url, andcapabilities.secrets. The same doc is dropped into the campaign-host dir~/.config/peregrin/serve/<name>.yaml. Tamias then rendersprovider.services[]as per-user units, written + daemon-reloaded.tamias driver exec <pkg> <verb> [args…]dispatches the driver's ops verbs (hooks,health,status,logs,config-schema,capabilities):hooks register|unregister [--dry-run] [--api-base <url>] [--token-env <NAME>]— upsert/remove the forge webhooksprovider.ingress[].hooks[]declare. Idempotent — the upsert matches on the exact hook URL (public_url+path). Secrets resolve by NAME through the env → keyring →~/.config/peregrin/envchain (GITHUB_TOKEN+PEREGRIN_WH_<OWNER>_<REPO>); values are never printed.--dry-runfirst — it prints the plan without touching the forge API or the secret chain.public_urlfronts a tunnel the operator confirms, sotamias deploynever auto-registers.health— JSON{ok, probes[]}: a github-webhookping(POSTto the ingresslisten+path,X-GitHub-Event: ping→200 pong) per ingress that declares both, elsesystemctl --user is-activeper provider unit.status— JSON per-unitis-active/is-enabled.logs [--lines N]—journalctl --userover the provider units (no follow — dispatch is bounded).
tamias uninstall <name>removes the provider units + store entry; the driver'suninstallverb removes the node config, its campaign-host file, and any legacy<name>.servicea pre-providerdeploywrote.~inexec/env_file/workdirexpands at unit-render orcampaign servetime — ExecStart argv is data, no shell.peregrin provision {install,deploy,uninstall}(with--dir,--name, optional--config) is the hidden provider entrypoint tamias invokes — it never writes service units itself.
libraries/docs-deploy is the pilot: provider.name: peregrin + services[].name: campaign renders the shared peregrin-campaign.service hosting every deployed bundle. Its tamias.yaml ships ingress[].hooks: [] — the bundle's main.yaml is a full peregrin import bupha artifact that owns its ingress inline (per-repo cmds/contexts/secret names), so manifest hooks would only generate a duplicate webhook node. See the bundle's README for the full operator flow.
The peregrin-node type — the daemon itself
libraries/peregrin-node manages the node daemon, not a campaign: type: peregrin-node, no main.yaml payload, and a provider.services[] entry (name: node, exec: peregrin serve). The driver recognizes the type and skips node-config generation on deploy — there is no campaign to host — while tamias deploy still renders the unit: peregrin-node.service (provider peregrin
- service
node, distinct from the sharedperegrin-campaign.service). The node readsPEREGRIN_*env, soenv_filepoints at~/.config/peregrin/env;health/statusfall back to unitis-activesince there is no ingress probe.