GLOSSARY.md

QuickStack

QuickStack deploys applications from container images or Git repositories into a managed cluster.

Language

Cluster Add-on: A QuickStack-managed Kubernetes platform extension that an administrator can install, update, inspect, and remove. Agent Sandbox is a Cluster Add-on; its installed controller and CRDs are not Agents. Avoid: plugin, App, Agent

Add-on: Short form for a Cluster Add-on.

Add-on Installation Source: The per-Add-on source that provides its Kubernetes manifests and version information; it may be a fixed code-defined release or an external release catalog. Avoid: universal add-on catalog

Add-on Release: An installable, versioned Add-on manifest selected by an Add-on Installation Source. Avoid: update flag, manifest URL when the release is meant

Trusted Add-on: A Cluster Add-on implemented and registered in QuickStack source code. Administrators cannot install arbitrary third-party Add-ons or manifests. Avoid: plugin marketplace, external Add-on

Add-on Configuration: The Add-on-specific configuration owned, stored, validated, and reconciled by that Add-on. QuickStack does not provide a generic configuration store. Avoid: global add-on configuration

Add-on Readiness: The operational state of an installed Cluster Add-on, determined by its declared Kubernetes resources. It does not prove that external runtime prerequisites for workloads using the Add-on are present. Avoid: runtime support

Add-on Lifecycle Status: The shared Add-on state reported as notInstalled, installing, ready, updating, uninstalling, or failed, with an optional detail message and installed version. Avoid: Add-on-specific status enum

Non-removable Cluster Add-on: A Cluster Add-on that QuickStack can install, inspect, and update but deliberately cannot remove because removal would leave host-level runtime changes behind. Its lifecycle never enters uninstalling. Avoid: broken Add-on, partially installed Add-on

gVisor Runtime Add-on: A Trusted, Non-removable Cluster Add-on that makes the gVisor runtime available on supported cluster nodes. It does not select a runtime for Agent Sandboxes. Avoid: gVisor plugin, Agent runtime selector

gVisor Release Version: The explicit, date-based gVisor release selected by QuickStack for installation and display, such as 20260921. It is the version of the gVisor Runtime Add-on. Avoid: latest, unpinned runtime version, Add-on SemVer

gVisor RuntimeClass: The optional Kubernetes RuntimeClass named gvisor, backed by io.containerd.runsc.v1. It is available alongside, and never replaces, the cluster's default runtime class. Avoid: default runtime, runsc RuntimeClass

gVisor-ready Node: A schedulable node on which QuickStack has statically verified the pinned gVisor installation, K3s configuration, active K3s service, and node readiness. QuickStack marks it with quickstack.dev/gvisor=true and quickstack.dev/gvisor-version after success. Avoid: gVisor-tested node, RuntimeClass-proven node

gVisor Node Version: The gVisor Release Version actually installed and statically verified on a gVisor-ready Node. It is represented by quickstack.dev/gvisor-version and does not change until that node's update succeeds. Avoid: desired gVisor version, planned node version

gVisor Add-on Configuration: The Add-on-owned Kubernetes ConfigMap that persistently declares the desired gVisor Release Version for the gVisor Runtime Add-on. It is not part of a generic Add-on configuration store. Avoid: global Add-on configuration, runtime version cache

Agent Sandbox Add-on: The Cluster Add-on that installs the Agent Sandbox controller and its extension CRDs, including SandboxTemplate and SandboxWarmPool. It does not create user workload resources. Avoid: Agent, Agent runtime

App: A deployable workload managed by QuickStack.

App Network Policy Configuration: The active network-policy configuration for an App, selected as either Simple or Extended. Avoid: advanced configuration, app firewall mode

In an App Extended Full Schema Write, the App Network Policy Configuration is provided explicitly as either its complete value or null; omitting it is invalid.

Agent Network Policy Configuration: The active egress network-policy configuration for an Agent, consisting of optional Internet access and detailed target-App rules. Avoid: agent firewall, app network-policy configuration

In an Agent Extended Full Schema Write, the Agent Network Policy Configuration is provided explicitly as either its complete value or null; omitting it is invalid.

Simple App Network Policy Configuration: An App Network Policy Configuration that uses the App's ingress and egress policy enums. Avoid: legacy configuration, basic firewall

Extended App Network Policy Configuration: An App Network Policy Configuration that uses detailed, separate ingress and egress rules. Avoid: advanced configuration, custom firewall

App Network Policy Rule: A detailed ingress or egress rule that permits traffic between one App and a target App on a port and protocol. Avoid: generic app allowlist, agent network-policy rule

App Network Policy Rule Source: The permitted source App of an extended ingress rule. Avoid: ingress target app

App Network Policy Rule Target: The permitted destination App of an extended egress rule. Avoid: egress source app

Configuration Migration: A one-time transformation of persisted QuickStack configuration from one supported shape to another, guarded so it runs at most once across server restarts. Avoid: migration when a Database Migration is meant, data migration

Network Policy Mode Migration: The Configuration Migration that replaces each App's active Simple App Network Policy Configuration with its equivalent Extended App Network Policy Configuration. Avoid: policy migration, extended upgrade

App Domain: A configured domain that exposes an App through Traefik. Avoid: public app address, ingress rule

Project Network Graph: A visual representation of the effective traffic routes between the Apps and Agents visible from a Project, including Traefik ingress permitted by each App Domain even when that App has Network Policies disabled. Avoid: network-policy-only graph, deployment topology

Agent: A long-lived, isolated container workspace managed by QuickStack for AI-assisted work. Avoid: App, fixed opencode runtime, automation run

Agent Name: A user-defined label for an Agent that does not have to be unique. Avoid: agent id, Kubernetes name

Agent Runtime Secret: Sensitive runtime context shared by an Agent's SandboxTemplate, such as its LLM Gateway URL and configured environment variables. It does not contain a virtual key. Avoid: public agent config, plain environment config

Sandbox Virtual Key: A LiteLLM virtual key created for exactly one Agent Sandbox instance. QuickStack keeps its value in a per-sandbox Kubernetes Secret so it can delete the key when the sandbox is stopped. Suspending and resuming the same sandbox retains the same Sandbox Virtual Key. Avoid: Agent virtual key, tag key

Sandbox Virtual Key Secret: The Kubernetes Secret that stores one Sandbox Virtual Key and identifies its owning Agent Sandbox. It is deleted on Stop even if deleting the corresponding LiteLLM key fails. Avoid: Agent Runtime Secret, tag key secret

Agent Environment Variable: A user-defined environment value for an Agent whose value is stored encrypted by QuickStack. Avoid: plain env var, app env var

Agent Rate Limits: CPU and memory requests and limits stored as integers (millicores for CPU, MB for memory) that control Kubernetes resource allocation per sandbox container instance. Avoid: resource quantities, K8s resource strings

Agent Container Configuration: Runtime startup settings for an Agent container, including command and arguments. Avoid: opencode config, app container config

Agent Warm Pool Replicas: The number of pre-warmed idle sandbox instances QuickStack keeps available for an Agent. Currently stored but ignored, and not editable in the UI, because warm pools are temporarily disabled (ADR 0015). Avoid: app replicas, running agent instances

Agent Source: The Source QuickStack uses to build or run an Agent. Avoid: agent config, general settings

Agent Build Output: The internal container image produced from an Agent Source and used by the Agent's SandboxTemplate. Avoid: agent source, saved container image source

Agent Model Configuration: The LLM Gateway and LiteLLM Model Alias selected for an Agent. Avoid: agent source when only model access is meant

Agent Template: A reusable definition that can create one or more preconfigured Agents and their supporting Agent-specific resources. Avoid: fixed opencode runtime, app template when referring to Agent creation

Agent Sandbox Manifest: The Kubernetes resource definitions QuickStack derives from a saved Agent configuration to deploy or start its Agent Sandboxes. Avoid: Agent Template, runtime configuration when the Kubernetes definitions are meant

Deploy (Agent): The explicit action that reconciles a saved Agent configuration from the database to Kubernetes SandboxTemplate and SandboxWarmPool resources. Avoid: auto-save, save-and-apply

LLM Gateway: A QuickStack-managed connection to a LiteLLM-compatible service that brokers model access for Agents. Avoid: built-in model provider, hidden control-plane service

LiteLLM Admin Key: A credential that allows QuickStack to manage models and virtual keys on an LLM Gateway. Avoid: agent API key, model API key

LiteLLM Model Alias: A model name exposed by an LLM Gateway for selection by an Agent. Avoid: provider model id when the LiteLLM alias is meant

Project Workload: A deployable resource contained in a Project: either an App or an Agent. Avoid: mixed workload, generic app

Volume: A persistent storage mount attached to an App or Agent, backed by a Kubernetes PersistentVolumeClaim. Avoid: disk, storage, PVC when referring to the domain concept

App Volume: A Volume attached to an App, optionally shareable with other Apps in the same project. Avoid: app storage, app disk

App Volume Filesystem Usage: The occupied and available space and the capacity of the filesystem of an App Volume. It excludes storage consumed by snapshots outside that filesystem. Avoid: Longhorn actual size, physical replica usage

Agent Volume: A Volume attached to an Agent, without backup scheduling. An Agent Volume is not shareable with other Agents or Apps. Its Volume Type is a Shared Agent Volume, a Per-Sandbox Agent Volume, or a Per-Custom-Tag Agent Volume. Avoid: agent storage, agent disk

Volume Type: The sharing and provisioning model of an Agent Volume: ALL (a Shared Agent Volume), PER_SANDBOX (a Per-Sandbox Agent Volume), or PER_CUSTOM_TAG (a Per-Custom-Tag Agent Volume). Avoid: volume mode

Shared Agent Volume: An Agent Volume of Volume Type ALL. Every Agent Sandbox instance of its Agent mounts the same Shared Agent Volume, and it persists independently of any sandbox. Avoid: shared disk

Per-Sandbox Agent Volume: An Agent Volume of Volume Type PER_SANDBOX. It is provisioned for one Agent Sandbox instance and is deleted with that sandbox. A Custom Tag distinguishes the sandbox it belonged to. Avoid: isolated volume

Per-Custom-Tag Agent Volume: An Agent Volume of Volume Type PER_CUSTOM_TAG. Its data belongs to a Custom Tag rather than to a sandbox, backed by a QuickStack-managed PersistentVolumeClaim per tag that outlives the sandbox. Avoid: per-tag volume, tag storage

Custom Tag: The optional tag given when an Agent Sandbox is started, used to identify that sandbox and its Per-Sandbox Agent Volumes and Per-Custom-Tag Agent Volumes. It is unique per Agent among existing sandboxes, so it is also a stable handle for Resume. It is encoded to derive the per-tag PersistentVolumeClaim name and is never used raw in a Kubernetes name. For LiteLLM ownership, its normalized value is the user_id of the Sandbox Virtual Key's LiteLLM user. Avoid: sandbox name, label

Suspend: Releasing the compute of a running Agent Sandbox (its Pod, CPU, and memory) while keeping the Sandbox object, its Service, and its Per-Sandbox Agent Volumes. Stop keeps its different meaning: delete the sandbox and its per-sandbox data. Avoid: stop, pause when Stop is meant

Resume: Recreating the Pod of a Suspended Sandbox with the same Per-Sandbox Agent Volumes and Shared Agent Volumes mounted. Avoid: restart, start when resuming the same sandbox is meant

Suspended Sandbox: An Agent Sandbox whose compute has been released by Suspend. It keeps its sandbox name, its Custom Tag, and its per-sandbox data, and reports status SUSPENDED. A Suspended Sandbox is the only way a Per-Sandbox Agent Volume outlives a sandbox. Avoid: stopped sandbox, sleeping sandbox

File Mount: A text file mounted into an App or Agent container at a configured container path. Avoid: config map when referring to the domain concept, mounted file

App File Mount: A File Mount attached to an App. Avoid: app config file, app mounted file

Agent File Mount: A File Mount attached to an Agent. Avoid: agent config file, agent mounted file

Workload Permission: A permission grant for one specific Project Workload inside a Project. Avoid: app permission when the workload may be an Agent

Running Workload: A Project Workload whose runtime instance is ready to serve user interaction or traffic. Avoid: deployed when describing user-visible readiness

Source: The origin QuickStack uses to build or run an App.

Configured Source: A Source with all required connection details selected and ready to be saved or deployed. Avoid: connected source, selected source when referring to readiness

Git HTTPS Source: A Git repository accessed through an HTTPS clone URL, optionally with username and token credentials. Avoid: git https, HTTPS repo

Git SSH Source: A Git repository accessed through an SSH clone URL using an app-specific deploy key. Avoid: SSH repo

Container Image Source: A container image reference QuickStack uses to run an App or Agent without building from Git. Avoid: Docker Container when referring to the domain concept

App Environment Variable: A user-defined runtime environment value injected into an App container. Avoid: build argument, build-time variable, secret

App Build Argument: A user-defined value made available to an App's container image build as a Docker build argument, and never injected at runtime. Avoid: build environment variable, build-time env var, runtime environment variable

Deploy Key: A public SSH key registered with a Git provider to grant repository access to a Git SSH Source. Avoid: SSH key when specifically referring to the provider-side access grant

Git Branch: The named Git ref selected as the source revision stream for an App or Agent. Avoid: branch name when referring to the selected source branch

App Node Port: A direct node-level exposure that maps a cluster node port to one container port and protocol on an

REST API Key: A user-owned credential for authenticating REST API requests with exactly the same permissions as its owning User. Avoid: token, secret, API token (when this specific credential type is meant)

REST API Key Name: A mandatory user-defined label used to identify one REST API Key among a user's keys. Avoid: description, alias

REST API Client: An external automation or tool that calls QuickStack via the REST API using a REST API Key. Avoid: integration user, bot user

Deploy Action: A REST-triggered action that applies the currently available deployment input for an App without forcing a new build. Avoid: redeploy job (when this domain action is meant)

Build-And-Deploy Action: A REST-triggered action that forces a new build for an App and deploys that build output. Avoid: deploy, rebuild (when this exact combined action is meant)

Deployment Request: An asynchronous REST request that starts a deployment-related action and returns immediately with a tracking identifier. Avoid: synchronous deploy call, blocking deployment

Deployment Webhook: An existing deployment trigger endpoint that starts deployment by webhook identifier. Avoid: API key deploy endpoint

API Key Hard Deletion: The permanent removal of a REST API Key record so it can no longer be used or recovered. Avoid: revoke, deactivate

POST Upsert: A POST-based write operation that creates a resource when no id is provided and updates it when an id is provided. Avoid: strict REST update, PATCH update (when this specific behavior is meant)

Full Schema Write: A POST Upsert where every required business field must be provided on every create and update; partial field writes are not supported and all sub-collections are fully replaced by the supplied list. Avoid: partial update, PATCH-style update

Nested Create Identity Stripping: The REST API behavior where sub-resource ids inside an App or Agent create payload are ignored so copied read payloads create fresh sub-resources. Avoid: cloning existing subitems, preserving nested ids on create

Subitem Ownership Guard: The rule that an existing nested sub-resource id can only update the sub-resource when it already belongs to the parent App or Agent being saved. Avoid: moving subitems between workloads, reassigning nested resources by id

API Key Self-Management: Management of a REST API Key by its owning User through authenticated profile interactions. Avoid: machine-managed keys

Direct Success Payload: A REST success response returns the resource payload directly without a wrapper envelope. Avoid: success envelope, wrapped success response

Problem Details Error: A REST error response follows RFC 9457 Problem Details format. Avoid: custom error envelope

API Key HMAC Hash: A deterministic server-side HMAC-SHA-256 digest of a REST API Key used for storage and lookup. Avoid: bcrypt key hash, reversible encryption

Shared Authorization Check: A transport-independent permission check used consistently by both server-side UI actions and REST API handlers. Avoid: duplicate auth logic per endpoint type

App Project Assignment: The project linkage of an App set at creation time and immutable afterwards. Avoid: moving app between projects

Default App Port: The automatically created initial app port 80 when a new App is created. Avoid: manual initial port requirement

Relationships

• An App can have zero or one Configured Source.
• A Project can contain zero or more Apps and zero or more Agents.
• An App belongs to exactly one Project.
• An Agent belongs to exactly one Project.
• An Agent has exactly one Agent Name.
• An Agent has exactly one Agent Source.
• An Agent has exactly one Agent Model Configuration.
• An Agent has exactly one set of Agent Rate Limits that apply per sandbox container instance.
• An Agent has exactly one Agent Container Configuration.
• An Agent Template can create one or more Agents.
• A Deploy (Agent) reconciles the saved Agent configuration to its Kubernetes SandboxTemplate and SandboxWarmPool.
• An Agent can have zero or more Agent Environment Variables.
• A running Agent has one shared Agent Runtime Secret and each running Agent Sandbox has one Sandbox Virtual Key Secret.
• An Agent uses exactly one LLM Gateway.
• A Suspended Sandbox can be Resumed by its sandbox name or by its Custom Tag.
• Suspend operates on the Sandbox and keeps it; Stop deletes the SandboxClaim and everything it owns.
• A Custom Tag is unique per Agent among existing sandboxes and is reusable after its sandbox is stopped.
• A Per-Custom-Tag Agent Volume is backed by one PersistentVolumeClaim per Custom Tag, owned by QuickStack and not deleted with the sandbox.
• QuickStack uses a LiteLLM Admin Key to list LiteLLM Model Aliases and manage Agent virtual keys.
• A Project Workload means an App or an Agent inside a Project.
• A Workload Permission belongs to exactly one Project Workload.
• An App can have zero or more App Environment Variables.
• An App can have zero or more App Build Arguments.
• An App Build Argument is available only while building a Dockerfile-based App.
• Runtime App Environment Variables are never passed as App Build Arguments, and App Build Arguments are never injected at runtime.
• App Build Argument values are not secret and must not hold sensitive data.
• An App can have zero or more App Node Ports.
• An App has exactly one active App Network Policy Configuration.
• Traffic between replicas of the same App is always permitted and cannot be disabled.
• A Network Policy Mode Migration replaces an App's active Simple App Network Policy Configuration with its equivalent Extended App Network Policy Configuration.
• An Extended App Network Policy Configuration can have zero or more App Network Policy Rules for ingress and zero or more for egress.
• An App Domain permits Traefik ingress to its App when Network Policies are active.
• An extended ingress rule identifies an App Network Policy Rule Source; an extended egress rule identifies an App Network Policy Rule Target.
• An App Network Policy Rule may reference an App in another project only when its user has a Workload Permission for that App.
• A Configured Source belongs to exactly one App.
• Only application workloads can use a Git HTTPS Source or Git SSH Source.
• A Git HTTPS Source belongs to exactly one App.
• A Git SSH Source belongs to exactly one App.
• A Container Image Source belongs to exactly one App.
• A Git Source has exactly one selected Git Branch before it can be saved.
• A Git SSH Source requires a Deploy Key before QuickStack offers Git Branch selection.
• An App Node Port belongs to exactly one App and exposes exactly one container port/protocol.
• A User can create zero or more REST API Keys.
• A REST API Key belongs to exactly one User.
• A REST API Key has exactly one REST API Key Name.
• A REST API Key Name is unique per User.
• A REST API Key is persisted as an API Key HMAC Hash.
• A REST API Client authenticates with exactly one REST API Key per request.
• A REST API Client can trigger a Deploy Action for an App.
• A REST API Client can trigger a Build-And-Deploy Action for an App.
• A Deploy Action is triggered through a Deployment Request.
• A Build-And-Deploy Action is triggered through a Deployment Request.
• An App can be deployed through a Deployment Webhook or a REST API deployment action.
• A deleted REST API Key uses API Key Hard Deletion.
• A Project write via REST API uses POST Upsert.
• An App write via REST API uses POST Upsert.
• An App created through REST API receives its id from server-side generation.
• An App or Agent created through REST API applies Nested Create Identity Stripping.
• An App or Agent write enforces Subitem Ownership Guard for nested sub-resources.
• An App Project Assignment is set once on create and cannot be changed by update.
• An App write via REST API uses Full Schema Write semantics: all required business fields must be present on every create and update, and all sub-collections are fully replaced.
• An App update must include projectId and its value must equal the existing App Project Assignment.
• An App write via REST API must include App Build Arguments; like envVars, the field is required on every create and update even when empty.
• A User performs API Key Self-Management only for their own REST API Keys.
• API Key Self-Management is implemented through profile UI and Next.js Server Actions, not REST API endpoints.
• A successful REST API response uses Direct Success Payload.
• A failed REST API response uses Problem Details Error.
• Each REST API route declares a Route Input Schema for every accepted query, params, or body input.
• Each REST API route declares a Route Response Model instead of writing success and error schemas inline.
• REST API handlers throw an API Exception for expected authorization and not-found failures.
• A Shared Authorization Check is used by server actions and REST API handlers.

Example Dialogue

Dev: "When the user edits a Git HTTPS Source, should choosing a Git Branch save the App?" Domain expert: "No, selecting the Git Branch only updates the current form; the App is saved when the user clicks Save."

Dev: "Can QuickStack list branches for a Git SSH Source before the provider knows its Deploy Key?" Domain expert: "No, the user must generate the key and register it as a Deploy Key with the Git provider before branch selection is shown."

Dev: "Can a user type a Git Branch manually when QuickStack cannot load branches?" Domain expert: "No, the Git Branch must be selected from the branches QuickStack loads from the configured Git source."

Dev: "Should QuickStack generate a new Deploy Key every time a user edits the Git SSH URL?" Domain expert: "No, QuickStack reuses the app's existing key unless the user explicitly regenerates it."

Dev: "Should the Source card show Git HTTPS as selected just because it is the database default?" Domain expert: "No, the card shows an empty connect state until the App has a Configured Source."

Dev: "What should happen when the user saves a Configured Source and deploys immediately?" Domain expert: "QuickStack saves the Configured Source, starts deployment, closes the source dialog, and shows deployment progress in the Overview tab."

Dev: "If an App uses an App Node Port, should a restrictive ingress policy still block that node-level traffic?" Domain expert: "No — creating the App Node Port is the explicit decision to expose that one container port/protocol through the cluster node."

Dev: "When I Stop a sandbox with tag alice, is its workspace gone?" Domain expert: "No. A Per-Custom-Tag Agent Volume is backed by a per-tag PersistentVolumeClaim that outlives the sandbox, so starting tag alice again reuses the same workspace."

Flagged Ambiguities

• "connect to a git https" means configuring a Git HTTPS Source for an App.
• "no app source chosen" means the App has no Configured Source, even if storage contains a default source type.
• "Docker Container Image" is the UI label for a Container Image Source.
• "build env variable" / "build-time variable" means an App Build Argument, never an App Environment Variable.
• "branch" means the selected Git Branch, not a build branch or deployment branch.
• "node portforwarding" means an App Node Port, not an ad hoc developer port-forward session.
• "CRUD REST API" for projects and apps means REST reads/deletes plus POST Upsert for create and update.
• "uniform JSON schema with status/data/error" was superseded by Direct Success Payload for success and Problem Details Error for failures.
• "bcrypt for API key hashing" was superseded by API Key HMAC Hash.
• "deployment trigger endpoint" may refer to Deployment Webhook or REST deployment endpoints and must be named explicitly.
• "API key management API" is not part of REST /api/v1; API key management is UI + Server Actions only.
• "immutable app projectId on update" means the field must always be provided and must equal the existing App Project Assignment; it can never be changed or omitted.
• "migration" may refer to a Database Migration (Prisma migrate deploy) or a Configuration Migration (startup data transformation); name the kind explicitly.
• "all apps in the project" for a migrated App includes database-type Apps, Apps with network policies disabled, and Apps already in Extended mode; only the App itself is excluded.