Skip to content

Glossary

This page is the single authoritative definition of the vocabulary that Shaken Fist's code, command line, and documentation use. Where a word is overloaded -- inside Shaken Fist, or against the vocabulary of an external tool -- the entry names the sibling meaning so that a reader who arrived by search is not misled. Other documents should link here rather than redefining these terms.

Definitions describe what the code does today. Entries which once carried a (planned) marker for the workload identity federation work have lost it: trusted issuers, mapping rules, identity tokens and scopes all exist now and are described here as they behave. See PLAN-auth-federation for the design. Should a future entry describe something not yet built, it will say so explicitly.

Entries are alphabetical. Each carries a short definition, a "Defined in" pointer to the authoritative code or documentation, and, where the term is overloaded, a "Not to be confused with" note.

access token -- A Shaken Fist-issued JWT, minted from a namespace key via /auth and nonce-bound to that key. The token's identity is the string <namespace uuid>:<keyname>, and it carries the minting key's nonce as a claim so that revoking the key immediately invalidates the token. Defined in shakenfist/util/access_tokens.py. Not to be confused with the release pipeline's OIDC token (see token and Release pipeline vocabulary).

agent -- The in-guest agent, sf-agent, which runs inside an instance and is reachable from the hypervisor over the side channel. Defined in docs/developer_guide/agent_protocol.md. Not to be confused with: an agent operation, which is the queued command object executed by the in-guest agent (docs/developer_guide/api_reference/agentoperations.md); or the unrelated sense in AGENTS.md, where "agent" means an AI coding assistant such as Claude Code or GitHub Copilot.

artifact -- A named, versioned, namespaced reference to a sequence of blobs. An artifact has a type: image, snapshot, label, or other. Lookup by reference accepts either a UUID or a name. Defined in shakenfist/artifact.py (see also docs/plans/PLAN-artifact-ux-rework.md). Not to be confused with a GitHub Actions / release "artifact", a build output of the CI and release pipeline (docs/developer_guide/release_process.md).

blob -- An immutable, content-addressed, reference-counted lump of bytes, identified only by UUID. Blobs are the storage that artifact versions point at, are replicated across nodes, and are deleted only when their reference count reaches zero. Defined in shakenfist/blob.py (see also docs/plans/PLAN-artifact-ux-rework.md). Note that documentation occasionally uses the lowercase word "blob" generically to mean "a lump of data"; the object type is the sense meant here.

capability -- The client's server-feature-probe mechanism: the client asks the server whether an optional feature is present before relying on it, for example sf_client.check_capability('blob-search-by-hash'). Defined in docs/user_guide/usage.md (the client "knows how to probe the server for capabilities") and docs/developer_guide/api_reference/blobs.md. Not to be confused with an authorization term: capabilities do not grant or restrict access in Shaken Fist. The authorization noun is scope.

cluster operation -- The internal work-queue object that tracks a unit of cluster-wide work through its own state machine. Defined in docs/developer_guide/database_internals.md ("Cluster Operation Tracking" and "Cluster Operation Storage and Work Queues"). Not to be confused with an agent operation, which is executed by the in-guest agent rather than by cluster daemons.

credential -- In the documentation this word appears mainly for MariaDB database credentials -- the username and password an operator configures for the database tier. Defined in docs/operator_guide/database.md. The platform's own credential concept is the namespace key, from which callers derive access tokens.

DatabaseBackedObject / DBO -- The base class that gives an object type its UUID identity, state machine, attributes, and events. Most user-visible object types (instances, artifacts, blobs, networks, uploads, nodes) derive from it. Defined in shakenfist/baseobject.py.

event -- The umbrella audit-log mechanism. Many operations -- object creation and deletion, authentication, any change to an object's data -- record an event against the relevant object. Events have typed categories: audit, mutate, status, usage, resources, prune, and historic, each with its own retention period. Defined in docs/user_guide/events.md. Note: "audit event" strictly means an event of type audit; documentation sometimes uses the phrase loosely to mean "the event that serves as the audit record", which may be of another type.

identity token -- An externally-issued JWT proving workload or user identity, for example a GitHub Actions OIDC token or an Authentik-issued token. It is presented to POST /auth/federated, along with a namespace and a mapping rule name, and exchanged for a scoped namespace key. The token is verified against the trusted issuer named by its iss claim: signature against that issuer's published keys, using asymmetric algorithms only, then audience, issuer and lifetime, then the rule's bound claims. An identity token is single-use per rule: once exchanged through a given mapping rule it cannot be exchanged through that rule again, though the same token may still be exchanged through a different rule to reach a second namespace. Validation is defined in shakenfist/federation.py and the exchange in shakenfist/external_api/auth.py.

instance -- The virtual machine object: a running (or startable) VM with disks, network interfaces, and a lifecycle. Defined in shakenfist/instance.py and docs/developer_guide/api_reference/instances.md. Not to be confused with the generic "daemon instance" / "replica" sense used in docs/developer_guide/database_internals.md and docs/operator_guide/database.md, where "instance" means one running copy of the sf-database daemon.

key -- Primary sense: a namespace key. Other in-tree senses of the word that a reader may land on: the inter-node service keys used for daemon-to-daemon authentication (the reserved _service_key* name prefix, docs/developer_guide/authentication.md); SSH keys used by the deployment tools (SSH_KEY_FILENAME, docs/operator_guide/installation.md); metadata keys, the names in an object's metadata map (docs/user_guide/metadata.md); configuration keys / options; and SQL primary keys. When this documentation says "key" without qualification it means a namespace key.

label -- An artifact of type label: a manually-curated pointer where the user explicitly chooses which blob each version uses. Its name is path-like (label or namespace/label), and it is created implicitly on first update. Defined in shakenfist/artifact.py (see also docs/plans/PLAN-artifact-ux-rework.md). Not to be confused with Prometheus/Loki metric and log labels (docs/operator_guide/events.md, docs/operator_guide/logging.md) or GitHub issue labels such as ci-failure (docs/developer_guide/workflow.md).

mapping rule -- A first-class object, owned by the namespace it targets, that is a standing claim-gated authorization to mint keys there: a trusted issuer reference, bound claims, the scopes minted keys receive, a TTL for those keys, and a prefix for their names. Managed under /auth/namespaces/{namespace}/rules by the namespace owner, unique on (namespace, name), and deleted with the namespace. Bound claims match exactly -- an exact string, or a list of acceptable strings -- with no globbing, regular expressions or prefix matching, and a rule must bind at least one claim and grant at least one scope, so it can neither accept every identity an issuer vouches for nor inherit the wildcard an unscoped namespace key would. Rules are consumed by POST /auth/federated, which is where an identity token becomes a key. Defined in shakenfist/mapping_rule.py and docs/developer_guide/api_reference/authentication.md.

namespace -- The tenancy and authorization unit: objects belong to a namespace, and a caller acts within one. Visibility extends to a caller's own namespace and to namespaces that trust it. Defined in shakenfist/namespace.py and docs/user_guide/objects.md. Not to be confused with Linux network namespaces, which the networking documentation uses heavily (docs/operator_guide/networking/overview.md).

namespace key -- The stored credential from which access tokens are minted: a bcrypt hash, a nonce, and an optional expiry. Scopes are recorded on the object and enforced on every request made with a token minted from it; a key with no scopes recorded mints wildcard tokens, which is every key predating the federation work. Provenance records where a key came from: keys minted by the federated exchange carry the rule, the issuer and the claims that were satisfied. /auth bcrypt-compares a presented secret against the namespace's unexpired keys and mints a token bound to the matching key's nonce. A key is a first-class object owned by its namespace, with its own lifecycle, events and soft delete. Defined in shakenfist/namespace_key.py (the object) and shakenfist/namespace.py (the keys, lookup_key, add_key and remove_key members), and described in docs/developer_guide/authentication.md.

network -- The virtual network object: a namespaced, isolated layer 2 broadcast domain, implemented as a VXLAN mesh spanning every node which carries it. Each network owns a netblock (the CIDR its addresses are allocated from, managed by an IPAM object), a cluster-unique VXLAN id (vxid), and switches for whether it provides DHCP, DNS and NAT. Instances attach to it through network interfaces, which are separate objects. Defined in shakenfist/network/network.py (the object), shakenfist/network/interface.py (the interfaces), and docs/developer_guide/api_reference/networks.md. Not to be confused with the network node role, the elected cluster ingress and egress point for all virtual networks (see node); with the underlying physical network the mesh is built on top of (the node_egress_nic and node_mesh_nic deployment settings in docs/operator_guide/installation.md); or with the netblock alone, which is only one attribute of a network.

node -- A cluster member machine. A node carries one or more roles, which are configuration, not object types:

  • primary node -- the node that runs the API and on which sf-client and authentication details are installed; one per cluster (docs/operator_guide/installation.md).
  • network node -- the elected, singular ingress and egress point for all virtual networks, where floating IPs live; one per cluster (docs/operator_guide/installation.md, docs/developer_guide/network_dispatcher.md).
  • hypervisor node -- a node that runs virtual machine instances (docs/operator_guide/installation.md).
  • database-tier node -- a node running an sf-database daemon against the shared MariaDB; none is elected (docs/developer_guide/database_internals.md, docs/operator_guide/database.md).
  • storage-only node -- a node that stores blobs but runs no VMs, used to hold blobs that are not needed by currently running instances (docs/features.md).

The node object itself is defined in shakenfist/node.py; it is the only object type that is never hard-deleted (docs/developer_guide/state_machine.md).

nonce -- The per-key value embedded in the access tokens derived from a namespace key and re-verified on every request. When a key is updated, deleted, or expires, its nonce changes or disappears; a request whose token carries a stale nonce is rejected. The nonce is therefore the revocation mechanism for derived tokens. Defined in the nonce section of the developer guide and enforced in shakenfist/external_api/base.py.

object / by reference -- Everything a caller interacts with is an object, usually referred to by a version-4 UUID string; the exceptions named by name are nodes, namespaces, and keys. Referring to an object by reference means passing either its name or its UUID, and a by-name lookup searches every object visible to the caller -- those in the caller's own namespace, and those in namespaces that trust it (plus shared artifacts for artifact commands). The caller's own namespace always wins, so nothing another namespace does can change what a name already means to you. Operations which modify an object resolve a name in the caller's own namespace only, so that a name can never resolve into another namespace and then destroy what it found there. Defined authoritatively in docs/user_guide/objects.md.

Release pipeline vocabulary -- The release process signs and publishes releases using Sigstore keyless signing, PyPI Trusted Publishers, and a GitHub Actions OIDC token (issuer token.actions.githubusercontent.com). This vocabulary -- "trusted publisher", "OIDC token", "keyless signing", release "artifacts" -- is entirely unrelated to the runtime authentication system (namespace trust, trusted issuers, identity tokens). Defined in docs/developer_guide/release_process.md.

scope -- A resource-family.verb string naming a class of operation that a namespace key (and the tokens derived from it) may perform, for example blob.read or instance.delete. Scope is the authorization noun in Shaken Fist. Families and verbs are derived mechanically from the resource class and the HTTP method, so an endpoint is governed the moment it exists. Three forms are special: * grants everything and is what a key with no scopes recorded carries; <family>.* grants every verb in one family; and cluster-admin is required, alongside the system namespace, for administrative endpoints. cluster-admin is hyphenated rather than dotted because it names no family, and so no family wildcard can synthesise it. Defined in shakenfist/external_api/scopes.py and docs/developer_guide/authentication.md. Not to be confused with (a) capability, which already names the client's server-feature-probe mechanism -- scope is not "capability"; or (b) the Linux ip scope attribute (scope global, scope link, scope host) that appears verbatim in docs/operator_guide/networking/overview.md.

side channel -- The virtio-serial / virtio-vsock transport between a hypervisor and the in-guest agent, over which the agent protocol's serialized messages flow. Defined in docs/developer_guide/agent_protocol.md (and used by name in docs/developer_guide/api_reference/instances.md). Not to be confused with the security-research sense of "side channel" (timing or cache side channels).

snapshot -- An artifact of type snapshot, produced from an instance's disk(s). Snapshots are created and listed through instance routes, not artifact routes. Defined in shakenfist/artifact.py (see also docs/plans/PLAN-artifact-ux-rework.md).

state / state machine -- Shaken Fist enforces a state machine per object type, defined by the state_targets map in each object class. States are per-type, so the same label can mean different things: created means "running" for an instance, "has at least one version" for an artifact, and "checked in at least once" for a node. Defined in docs/developer_guide/state_machine.md. Note the soft-delete state deleted (the object is hidden from the API) is distinct from the later hard deletion that removes it from MariaDB; and that instances additionally have an orthogonal power-state axis (docs/operator_guide/power_states.md).

stray vxlan -- A vxlan device present on a node which matches no network that node should be carrying. Strays are residue: from a teardown which did not finish, or from a network which has since been hard deleted. A stray which has persisted for MAINTAIN_STRAY_VXLAN_GRACE_SECONDS is reaped (its devices deleted, with a reaped stray vxlan audit event on the node) when no networks row claims its VXLAN id, torn down through an ordinary network operation when the network still exists but no local instance uses it, and otherwise left alone and logged once. Defined in shakenfist/daemons/network/maintain.py; the operator view is stray vxlan reaping. Not to be confused with a network in delete_wait whose devices are still present: that network's row still exists, so its devices are not stray and are never reaped.

system namespace -- The reserved administrative namespace. Membership of system is exactly what caller_is_admin checks today: a caller whose token resolves to the system namespace is treated as an administrator. Defined in shakenfist/external_api/base.py.

token -- Primary sense: an access token. Not to be confused with the release pipeline's GitHub Actions / Sigstore OIDC token (docs/developer_guide/release_process.md), which is unrelated to runtime authentication and is closest in nature to an identity token.

trust -- The existing namespace-to-namespace visibility grant: if namespace A trusts namespace B, then callers in B can see A's objects by reference. Visibility only -- B may read A's objects and may create new ones in A (the "gifting" pattern), but may not delete or modify what A already has. Defined in shakenfist/namespace.py (the trust member and add_trust/remove_trust) and docs/operator_guide/authentication.md. Not to be confused with: a trusted issuer, which is about accepting external token issuers rather than sharing objects between namespaces; the release pipeline's Sigstore / PyPI "Trusted Publisher" vocabulary (see Release pipeline vocabulary); or generic network-trust prose elsewhere in the documentation.

trusted issuer -- An external token issuer the cluster is configured to accept, recorded with its JWKS location and expected audience. Cluster level rather than namespaced, because deciding who may vouch for identities is an administrative decision, and managed through /auth/issuers by administrators only. Defined in shakenfist/trusted_issuer.py and docs/operator_guide/authentication.md. Not to be confused with namespace trust, nor with the release pipeline's "Trusted Publisher" (see Release pipeline vocabulary).

upload -- The short-lived staging object used to stream bytes to a node before they are turned into a blob. It backs the /upload REST resource. Defined in shakenfist/upload.py. Not to be confused with sf-client instance upload -- the agent-protocol file upload into a running instance (docs/developer_guide/agent_protocol.md) -- which is a different mechanism that happens to share the word.

📝 Report an issue with this page