---
title: "Glossary"
description: "The words ply uses, what each one means, and the naming rule that keeps them consistent."
canonical: https://plybox.sh/docs/glossary/
---

# Glossary

One word per concept, used the same way everywhere — docs, CLI output,
error messages. If a page contradicts this glossary, the page is wrong.

## Artifacts

| Term | Meaning |
|---|---|
| **image** | a `.img` file — one immutable, deterministic squashfs |
| **package** | an inert image: files plus a manifest, no entrypoint |
| **app** | a package *with* an entrypoint — something runnable |
| **base** | the one package per graph that owns `/` (FHS, libc, `/bin/sh`) |
| **keg** | a package's private prefix directory, `/opt/<name>-<version>/` |
| **store** | the content-addressed local cache (`store/sha256:<hash>/`) |
| **source** | a URL template dependencies are fetched through |
| **registry** | the file host a source points at — any dumb file host qualifies |

## Running things

| Term | Meaning |
|---|---|
| **instance** | one running copy of an app (`foo.3`) — own IP, own netns, own cgroup |
| **slot** | the numbered position `<n>` in `<app>.<n>`; persists across restarts and anchors volumes and state |
| **scale** | the instance count of an app on a host — `--scale 3` |
| **container** | the isolation *mechanism* wrapped around an instance: namespaces, cgroup, seccomp |
| **process** | the entrypoint PID inside an instance |
| **volume** | a persistent directory bind-mounted into an instance — per-slot by default, shared by opt-in |

The three running-layer words name three different things and are not
interchangeable. An **instance** is the unit of identity — what you scale,
list in `ply ps`, and route traffic to. It runs *in* a **container** — say
"container" when talking about isolation and security, never when counting.
Its entrypoint is a **process** — say "process" when talking about signals,
exit codes, and restarts.

## Traffic and machines

| Term | Meaning |
|---|---|
| **pool** | an app's running instances as a traffic target — what `--publish` balances across and `ply proxy` emits a backend for |
| **publish** | expose a pool on a real host port: `ply run --publish` makes the run parent bind it and L4-balance the pool (the explicit exception to "ports are labels") |
| **edge** | the proxy app (e.g. Caddy) fronting pools; ply emits its config and never proxies itself |
| **host** | one machine running ply |
| **fleet** | the declared list of hosts — an inventory file, not a membership protocol |
| **deploy** | replacing an app's version by rolling its pool one instance at a time, health-gated |
| **composition** (stack) | several apps wired in one `ply.toml` (`[[service]]` blocks) — registry services, local dirs, or `git+` repos — started together by `ply up` |
| **service** | a prebuilt *runnable* app in the registry's `apps/` namespace (`ply run postgres@17`); contrast with a keg, which is an inert library |
| **dev overlay** | `ply.dev.toml` — gitignorable run-time overrides (entrypoint, env, links) applied to dir runs only, never baked into images |

## Params

| Term | Meaning |
|---|---|
| **param** | a named value a manifest declares in `[params]` (or gets for free as a built-in fact) that other stack members interpolate with `{app.param}` |
| **fact** | a built-in param — `name version host port addr base_url scale arch image` — resolved from the graph and lockfile, never declared |
| **live param** | a runtime-only fact (`state instances started_at restarts`, plus anything an app self-publishes) — read from `/run/ply/<app>/<param>`, waited on with `after`, never interpolated into env |
| **minted secret** | a `{ secret = true }` param: ply generates the value on first start and stores it as a 0600 file — the file is the truth until deleted |
| **external secret** | a `{ secret = true, external = true }` param: ply never mints it — startup refuses until the operator provides it |
| **taint** | the mark a secret param carries through interpolation — any composed value that embeds one (`{db.url}` embeds `{db.password}`) is masked in `ply up --plan` output (v1's only masked surface) |

## Banned words

- **cluster** — industry-wide it means machines under a shared control
  plane. ply has no control plane; machines are a *fleet*, an app's
  instances are a *pool*.
- **node** — implies membership in a coordinated graph. Say **host**.
- **pod / replica / orchestrate** — they drag in semantics ply
  deliberately doesn't have.

## The naming rule

Borrow a word only when ply's semantics match the industry's exactly
(*host*, *pool*, *edge*, *fleet*). Coin a word when the concept is
genuinely ply's own (*keg*, *slot*, *craft*). Ban words that promise a
control plane ply refuses to build (*cluster*, *node*, *pod*).