1.4. Container

The container exists to hand the assistant to someone else: the harness, its dependencies and the embedder in one image, with — in a private image — the building host’s retrieval index, normative store and team knowledge as well (Three profiles). The recipient mounts their own checkouts and points it at a model endpoint.

This chapter is for whoever builds the images: what goes in, how a deployment’s content gets there, and how an image is published. To run a published one, read Running the images, the user’s page, instead.

The image is defined in docker/; the scripts that build, run and publish it are in scripts/docker/, and scripts/spear-image drives them (Managing images).

File

Purpose

docker/Dockerfile

The image. Do not build it by hand — see Two build contexts.

docker/entrypoint.sh

Refuses to start on the two failures that are otherwise silent.

docker/projects.docker.json

The corpus registry, in relative paths. Generated by gen-registry.py and not in the repository.

docker/README.md

A pointer to these pages, kept beside the Dockerfile.

scripts/spear-image

The operator’s entry point: build, list, inspect, run, save, load, push, erase.

scripts/docker/build.sh

Builds, wrapping both contexts.

scripts/docker/spear-docker.sh

Runs, deriving the mounts and carrying the three --security-opt flags.

scripts/docker/push.sh

Publishes, refusing a private image without --allow-push.

scripts/docker/stage-*.py, gen-registry.py

What build.sh stages into its contexts.

1.4.1. Managing images

Put the tree’s commands on PATH once per shell, from the repository root:

$ cd ~/spear && . ./env.sh

Only scripts/ goes on PATH. scripts/docker/ holds a build.sh, and a shell that has also sourced another tree’s env.sh with a build.sh of its own would then have two.

1.4.1.1. Base and project: get and update

The tiered images — harness → base → project — have two option-free verbs over build, so that neither you nor a colleague has to remember where an image lives or which flags built it. Everything they need is in client/local.conf.

$ spear-image get base            # pull from the registry, else load the shared tarball
$ spear-image run base --reds     # start a session against the model endpoint
$ spear-image update base         # rebuild from local.conf, refresh the tarball, try to push
$ spear-image get project         # base + a deployment's spear-private
$ spear-image update project

get is idempotent: an image already present is left alone. It tries the registry first (SPEAR_REGISTRY_IMAGE, the full repository path), then a directory of tarballs a colleague can reach (SPEAR_SHARE_DIR, default the tree’s parent), each named spear-<tier>-<version>.tar.zst.

update rebuilds only — from the contents local.conf names (SPEAR_COMMONS for the base, SPEAR_PROJECT_TREES and SPEAR_BAKE for the project) — then refreshes that tarball and, if a registry is set, tries to push. Re-indexing a corpus is a separate, deliberate step (Refreshing the index): it takes hours, and a rebuild is not the place for it. update base builds the harness first if it is missing; update project needs the base present and says so if it is not.

The lower-level build commands, and the flat public/reds/private profiles, follow.

$ spear-image build private               # spear:<version>-private
$ spear-image build private --bake so3,so3-doc
$ spear-image build private --knowledge so3      # common state, see below
$ spear-image build public                # spear:<version>-public
$ spear-image list                        # profile and label of each
$ spear-image inspect private
$ spear-image run private -- --auto       # spear-docker.sh options, then -- harness args
$ spear-image save private                # -> spear-private.tar.zst
$ spear-image load spear-private.tar.zst
$ spear-image push ghcr.io/<org>/spear:<version>-public
$ spear-image erase private [--cache]     # or public, all, a tag

A profile names the tag build.sh gives by default, spear:<version>-<profile>, where the version is the release the tree is (scripts/spearversion.sh: the latest v* tag, else the fallback the release sets, such as 0.3.0); anything containing a : is taken as a tag. spear-image decides nothing the scripts under it would not: build.sh still decides what a profile may carry and push.sh still refuses a private image without --allow-push.

erase --cache also prunes the build cache. Removing a private image does not remove the layers it was built from — the licensed documents and customer trees it copied stay in the cache until that is pruned.

1.4.2. Daily use

spear-docker --reds --auto        # what `spear-chat --reds --auto` does

spear-docker is scripts/docker/spear-docker.sh linked onto PATH beside spear-chat. Its own options are --reds, --endpoint URL, --state DIR and --mount DIR; everything else is passed to the harness unchanged. It runs the private image of this machine, spear:<version>-private (SPEAR_IMAGE names another), and needs the native installation beside it, from which it reads the registry. Three things the runner does that the native launcher does not have to:

The SSH tunnel stays on the host. --reds opens it exactly as spear-chat.sh does, reading the same reds.conf, then hands the container SPEAR_API_BASE=http://127.0.0.1:8082/v1. Putting the tunnel inside would mean shipping the keys and ~/.ssh/config into an image meant to be handed around; --network host makes 127.0.0.1 the same thing on both sides anyway.

Every tree is bound at its own absolute path. The harness runs its tools in the cwd, whatever the corpus (Retrieval), and build systems record absolute paths — CMake caches, BitBake stamps, toolchain locations — so a tree mounted elsewhere builds against compilers that are not there. An identity mount keeps both working, and the host cwd needs no translation: it is passed as the container’s working directory unchanged. This is the workstation mode; a colleague without the repository mounts under /corpora instead (Running the images).

Session state is written outside the image, as the host user. History, workspace knowledge, trajectories and the audit trail accumulate; docker run --rm would throw them away, and a container running as root would leave them owned by root and unreadable to the harness running natively. The default is ~/.spear/state, mounted on /state, overridable with --state DIR or SPEAR_STATE_DIR. What that directory holds is listed in Directory layout; evidence kept inside the image would be lost with the container that produced it.

External capabilities are not baked: capabilities.json is a machine’s own file, and the MCP servers it starts must exist where the harness runs. A container that needs them is given the file through a mount and SPEAR_CAPABILITIES_FILE (External capabilities).

1.4.3. What is baked, and what is not

Content

Where

Why

harness + venv

image

pinned, reproducible

embedder (bge-m3)

image, 4.3 GB

fetching it on first run is a surprise on a machine that may have no Hugging Face access at all

ChromaDB index

private image if the building host has one; as large as what the host indexed, several GB

re-indexing takes hours and needs every corpus tree present — the one thing a newcomer does not have

rules, skills, benches, notes corpus

image if present

a deployment’s own content; see below

corpora/

image

cross-cutting API references the host generated (such as the musl header snapshot of corpora/refresh-musl-headers.sh), attached to every session without duplicating them into each project index

source trees

mounted

working copies that change daily; an image would be stale the next morning

model weights

neither

the harness talks to an endpoint, it does not host a model

1.4.4. Two build contexts

build.sh passes two main ones, and the reason is size:

. (default) → client/

Harness code. Narrow on purpose: a wider context would be re-transferred on every build and would invalidate the 4.3 GB embedder layer.

repo (named) → the repository root

Only corpora/, docker/entrypoint.sh and the generated docker/projects.docker.json are taken from it. A named context is fetched lazily — BuildKit transfers only the paths actually COPY-ed — so pointing it at a tree that also holds model weights costs nothing.

The index and the other optional inputs are named contexts of their own (The optional inputs).

A bare docker build therefore fails on the missing --from=repo.

1.4.5. The optional inputs

Five of the things the image would like to carry are not in the repository and cannot be: the retrieval index is built on the host and gitignored, and the rules, the skills, the benches and the shared notes corpus are a deployment’s own content. Each is a named context of its own, resolved by build.sh in three steps: the environment variable, else the in-tree directory, else an empty directory — so a clean clone builds an image that simply carries less.

Context

Override

In-tree default

index

SPEAR_INDEX_DIR

client/chromadb

rules

SPEAR_RULES_DIR

client/rules.d

skills

SPEAR_SKILLS_DIR

client/skills

benches

SPEAR_BENCH_DIR

client/benches

notes

SPEAR_NOTES_DIR

claude/

build.sh prints which of the five it found and which it did not, so an image that carries less says so at build time rather than at the first question. An empty context still creates the directory, so the harness finds an empty directory rather than no directory — which is the difference between “no rules” and a stack trace.

SPEAR_RULES_DIR, SPEAR_SKILLS_DIR and SPEAR_BENCH_DIR are the variables the harness itself reads at runtime (Content the deployment owns), so one setting covers both the native run and the image.

Two further contexts are staged rather than pointed at, because neither is a directory that happens to be in the right shape already: the normative store is filtered per document, and the corpus trees are a named subset of a registry that may run to hundreds of gigabytes.

1.4.6. Three profiles

An image that carries a normative store is one somebody can be handed. What it may carry is decided per build, and the default is the one that is safe to give to anyone.

$ scripts/docker/build.sh --profile public
$ scripts/docker/build.sh --profile reds --bake so3,so3-doc,acme-firmware
$ scripts/docker/build.sh --profile private --bake so3,acme-firmware

Profile

What it carries

public

only normative documents that declare themselves PUBLIC; of rules, skills, benches and notes only the files the repository tracks; no retrieval index (it holds chunks of every corpus on the host) and no baked tree or workspace knowledge (--bake and --knowledge are refused). Anything withheld is printed as WITHHELD. Labelled redistributable=true.

reds

for the people of one institute, who have none of the trees: the corpora --bake names (required), of the index only their collections, of rules, skills and benches only what their scopes admit (a rule scoped to an absent corpus, a skill written for a customer, stay out), PUBLIC normative documents only, no notes corpus. The machine’s own content tree is read first; SPEAR_CONTENT_TREES, a colon-separated list of further trees (a project checkout’s spear-private/ with its rules.d/, skills/, benches/), is merged after it, each file by the same scope rule. The build prints LEFT OUT beside each thing it cut. Labelled redistributable=false: it goes to the institute’s registry, and push.sh refuses any other without --allow-push.

private

everything the building host has, licensed documents and the original PDFs included where the store retained them. Labelled redistributable=false.

Which document is which is never a list kept in this repository. Every ingested document already records source_origin and raw_pdf_retained in its manifest, and stage-standards.py reads them. A list here would have to name a customer’s standard in order to exclude it, would go stale on the next ingestion, and would leave the whole decision one forgotten edit away from shipping a licensed document. A manifest that declares nothing is treated as licensed.

Important

The active binding travels only if the document it names travelled. A binding pointing at an absent store is worse than none: the session opens looking bound and answers from nothing. Where the image carries exactly one document, the entrypoint binds it at startup — through the harness, so the fingerprints are computed rather than fabricated.

1.4.7. Baking the trees

--bake copies named registered corpora into the image, at the paths the generated registry already resolves them to. Nothing is baked by default, and a bind mount on /corpora still shadows whatever was — so a workstation keeps working from its own checkouts, and only the handed-over container relies on what is inside.

A baked corpus must be registered and indexed on the host first. The image ships the index; a tree whose collection is absent answers with no retrieval at all, which is the whole reason the tool exists.

$ spear-corpus add acme-firmware ~/src/acme-firmware
$ spear-index ~/src/acme-firmware
$ scripts/docker/build.sh --profile private --bake so3,acme-firmware

When --bake is used the image’s registry is restricted to what the image actually carries. Otherwise the recipient opens the container to a list of corpora they do not have and cannot get.

1.4.8. Common and local state

An image carries a common state, /opt/spear/common, that everyone who runs it reads and nobody writes: the normative store and, when the build is asked for it, the workspace knowledge of named projects. Each user keeps their own state in the directory mounted on /state, where everything a session writes goes.

$ spear-image build private --knowledge so3,so3-doc
$ spear-image build private --knowledge all

Only active records travel, each at its current version: proposals nobody accepted, revoked records and the earlier wording of an amended one stay with the user who built the image. Knowledge of an unregistered tree never travels, since it is named after a path on the building host. A recipient’s record follows the project by its registered name, so the project must be registered under the same name in the image’s registry.

A user’s change to a common record (revoking it, amending it, or the record going stale because their tree differs from the builder’s) is copied into their own state and shadows the common one there; the image is not changed. Shipping new knowledge is a new build.

1.4.8.1. Consolidating

The team keeps its common store on the building host, in the directory SPEAR_COMMON_STATE_DIR names (machine.env is the place to set it), and --knowledge ships from it; without one, the builder’s own store is shipped. spear-consolidate merges users’ stores into it, so that what each of them learns reaches everyone at the next build:

$ spear-consolidate ~/.local/state/spear/knowledge.sqlite3 alice.sqlite3
$ spear-consolidate ~/.local/state/spear/knowledge.sqlite3 alice.sqlite3 --apply
$ spear-image build private --knowledge so3

A user’s store is knowledge.sqlite3 in their state directory: the one mounted on /state for a container, ~/.local/state/spear on a workstation. Without --apply the command only reports.

Outcome

When

added

an active record the common store does not have

updated · revoked

a common record the user amended, accepted or revoked; the common store takes it with its history

duplicate

the same fact, already common under another id

conflict

not merged: a common record changed since the user copied it, or a new fact that contradicts an active common one. Settle it in either store and run again; the command exits 1 while any remains

skipped

a proposal (the user accepts it first), or a record stale in the user’s tree only

Knowledge describes the building host’s trees, customer code included, so --knowledge needs --profile private.

1.4.9. A deployment’s own content, and how it gets in

A deployment keeps what is specific to it outside the checkout: its rules, its skills, its benches, the trees it works on and the normative documents it answers from. client/machine.env is the one untracked file that says where those live, and it is read by the launcher, by spear-corpus and — since it decides what an image carries — by scripts/docker/build.sh.

Everything therefore reaches an image by one of three routes, and none of them is a second repository:

What

How it gets in

rules, skills, benches

machine.env sets their variables (Content the deployment owns); build.sh resolves them as named contexts (The optional inputs)

the normative store

staged per document by profile (Three profiles)

the corpus trees

--bake, once each is registered and indexed on the host

workspace knowledge

--knowledge, as the image’s common state (Common and local state)

Important

build.sh reads machine.env for exactly this reason. Without it the three variables are unset, the table falls back to the in-tree directories — a README in each — and the build reports them as found, because they are directories and they exist. The image then ships a harness with no rules and no skills and announces neither: the failure machine.env exists to prevent on a workstation, reproduced in the artefact handed to someone else, where it is harder to notice and impossible to fix from inside.

1.4.9.1. There is no second image

A deployment’s private material is content, not an application: there is no harness in it, nothing to execute, and so nothing to build an image around. It is not packaged separately — it is what makes a private image a private image.

Start to finish, on the machine that has the content:

$ spear-corpus add acme-firmware ~/src/acme-firmware   # register…
$ spear-index ~/src/acme-firmware                      # …and index
$ scripts/docker/build.sh --profile private --bake so3,acme-firmware

What the build reports is what the image carries:

settings  …/client/machine.env
rules     …/rules.d
skills    …/skills
benches   …/benches
standards <licensed document>  (LICENSED_STANDARD)
standards bound on open: <licensed document>
corpora   acme-firmware -> /corpora/…

The recipient opens a container already bound, with the rules, the skills, the index and the trees, and nothing to mount.

Note

The variables that build a corpus rather than use one — the path to a source PDF, the working tree a pilot drives — are deliberately not baked. They name host paths that do not exist in a container, and the corpus they produce is already inside it. They belong on the machine that builds the image, not in what is handed over.

1.4.10. Publishing, and not publishing

$ docker tag spear:<version>-public ghcr.io/smartobjectoriented/spear:<version>-public
$ scripts/docker/push.sh ghcr.io/smartobjectoriented/spear:<version>-public
$ scripts/docker/push.sh reds-gitlab.heig-vd.ch:5050/<group>/spear:<version>-reds
$ scripts/docker/push.sh ghcr.io/someone/spear:<version>-reds                  # refused
$ scripts/docker/push.sh <private-registry>/spear:<version>-private            # refused
$ scripts/docker/push.sh --allow-push <private-registry>/spear:<version>-private

A public image goes to the GitHub container registry of the project, where Running the images tells colleagues to pull it from. A reds image goes to the institute’s own registry, reds-gitlab.heig-vd.ch unless SPEAR_REDS_REGISTRY names another host: the image name must start with that host, or the push is refused without --allow-push. A private image goes only to the private registry of the organisation that owns its content; where that is, and how its users run it, is documented with that content, not here.

The guard reads the label, not the tag. A tag gets retyped, shortened and reused; a label travels with the bytes through docker save, a registry and back. An image not built by build.sh carries no label at all and is refused rather than guessed at.

Warning

--allow-push on a private image is a decision about a licence and a contract, not about a registry: it puts a licensed corpus and a customer’s source on that registry’s infrastructure, under whatever access policy it has today. It costs a deliberate word for that reason.

1.4.11. Relative corpus paths

projects.docker.json is build output: gen-registry.py derives it from this machine’s projects.json on every build, and it is gitignored. A committed copy would be a published map of one developer’s disk — corpus names, federations and the collection hash of each — and stale the moment a corpus was added. A clone with no projects.json gets an empty registry and an image that registers nothing, which is the honest answer: the operator registers their own trees. The one registry the repository carries by hand is client/projects.example.json, and it is a template.

It registers every corpus relative to SPEAR_CORPUS_ROOT (/corpora in the image), where a workstation registry uses absolute paths under the operator’s home. That is what makes one image work for someone whose checkouts live elsewhere; resolve_corpus_path() leaves absolute paths untouched, so a workstation registry works unchanged (Retrieval).

A tree the host does not have is not an error. The entrypoint prints what resolved and what did not, at startup, rather than letting a missing corpus surface three questions later as an empty retrieval.

1.4.12. Mounts are derived, not listed

spear-docker.sh computes its binds from the registry itself: one per registered corpus, plus the repository and the current working directory, dropping any path already inside another, each at its own absolute path. /usr/local/bin and /opt/toolchains are added read-only, for the cross-toolchains, and --mount DIR adds a tree a build needs that is not a corpus. A corpus added to the registry is therefore mounted without touching the script. The repository is mounted whole and read-write, so anything kept inside the checkout — model weights included — is visible to the container.

1.4.13. The three flags that are not optional

--security-opt seccomp=unconfined --security-opt apparmor=unconfined
--security-opt systempaths=unconfined

The harness runs every command inside bubblewrap and refuses to run any without it (Sandbox). Docker’s default seccomp profile blocks clone(CLONE_NEWUSER), so bwrap cannot start, and the failure surfaces as sandbox unavailable — which reads like a broken harness rather than a missing run flag. bwrap also mounts a fresh /proc for each command, which Docker’s masked system paths prevent unless systempaths=unconfined is given. spear-docker.sh passes all three, and entrypoint.sh tests bwrap first and prints exactly this if it cannot.

None of the flags grants the container new privileges on the host: all three are about letting an unprivileged namespace be created inside it. The sandbox is still what confines the model’s commands, and it is still doing its job.

spear-docker.sh also passes --memory, --pids-limit and --cpus with SPEAR_RESOURCE_CONTROL=delegated: there is no systemd inside the container to scope each command, so the limits are enforced by Docker for the container as a whole (Resource control).

1.4.14. Refreshing the index

The baked index is a snapshot. Re-index on the workstation, then rebuild: chromadb/ is copied late in the Dockerfile, so only that layer and the ones after it are rebuilt.

spear-index /path/to/tree     # updates chromadb/ on the workstation
scripts/docker/build.sh --profile private

1.4.15. Design rationale: retrieval stays in the client

This section records a design decision rather than a procedure.

The obvious economy is to move the embedder and the index onto the machine that already serves the model, and keep a thin client here. It was costed and declined; the numbers are worth keeping, because the idea comes back every time someone looks at the image size.

What it would save, measured on a development workstation:

Removed from the local install

Size

nvidia/ + torch/ + transformers + sentence-transformers

4.0 GB

the bge-m3 weights

4.3 GB

the ChromaDB index (grows with what is indexed)

~5 GB

total, leaving ~0.2 GB of client

~13 GB

The image would fall from 17.1 GB to roughly 5 GB, and the ten-second embedder load on the first query of a session would disappear, since the model would stay resident server-side on a GPU. Latency is not the objection: a round trip through the SSH tunnel that is already open measures 17 ms, against ~100 ms for a local CPU embedding. (The offload worker, server/embed/worker.py, could not be used as it stands: it serves one request per SSH invocation, 350 ms, which is right for indexing tens of thousands of chunks once and wrong for three embeddings a turn (Retrieval). It would need a persistent service behind the tunnel.)

It was declined for three reasons, in increasing order of weight:

  • It ends offline operation. Retrieval is what makes answers about a project reliable (Measured effect). Making it require a VPN and a reachable GPU host means a session on a train is not a degraded session, it is a different assistant.

  • It empties the container of its purpose. The image exists so that retrieval works the moment it starts, on a machine that may have no Hugging Face access at all. A 5 GB image that needs a tunnel to answer anything is a different product, not a smaller one.

  • A GPU host is often a shared login. Collections are named from the corpus’s absolute path, so two people indexing the same path under one account would write into the same collection. Fixing that means per-user prefixes and a shared ChromaDB on a filesystem other users already fill.

The work itself is small – about a day: a retrieve endpoint doing embedding and query in one round trip, a second port forward in spear-chat.sh, ten PersistentClient call sites and five embedding ones. Cheapness was never the question.