1.2. Running the images
This chapter is for a colleague who has never built SPEAR and wants to use it: pull the image, give it your checkouts and a model endpoint, and start asking. How the image is made is in Container; nothing here needs it. At the institute, skip to Running the reds image: that image brings its own trees and index.
1.2.1. What you need
Docker (Engine 24 or later), able to run as your user.
The checkouts you want to ask about. The public image knows the SO3 family of trees —
so3, its documentation,u-boot,avz,qemu,atfand the libraries vendored underso3/usr— and expects them where Laying out your checkouts says.A model endpoint: any OpenAI-compatible server (
llama-server, vLLM…) reachable from your machine. The image does not contain a model. The Anthropic API can answer questions and normative requests, but changes run on the coding core, which needs an OpenAI-compatible endpoint.
1.2.2. Getting the image
Public images are published on the GitHub container registry, one tag per release:
$ docker pull ghcr.io/smartobjectoriented/spear:<version>-public
<version> is the release you want, e.g. 0.3.0. The image is labelled
redistributable=true: you may pass it on.
At the institute, the image to use is the reds one: it carries the
shared trees themselves, their retrieval index and the rules written for them,
so nothing below about laying out checkouts is needed to start. It lives in
the institute’s own GitLab registry and is for its members; log in with your
GitLab account (a personal access token with the read_registry scope as
the password) and pull:
$ docker login reds-gitlab.heig-vd.ch:5050
$ docker pull reds-gitlab.heig-vd.ch:5050/reds-general/spear/spear-registry/spear:<version>-reds
Until that registry’s certificate is renewed, the same image is on the GitHub container registry as a private package of the organisation, for its members:
$ echo <token with read:packages> | docker login ghcr.io -u <github user> --password-stdin
$ docker pull ghcr.io/smartobjectoriented/spear-reds:<version>-reds
It is labelled redistributable=false: it stays within the institute. A
checkout of your own mounted at /corpora shadows the baked copy of the same
tree, so you can work on your branch and keep the index.
1.2.3. Running the reds image
The reds image carries the trees, their index and the rules, so there is
nothing to lay out and nothing to index: the steps below are all of it. What
it does not carry is a model, which the institute serves on its GPU host; the
container reaches it through an SSH tunnel you open on your machine.
Access. Be on the HEIG-VD VPN, and have an SSH key authorised on the inference host’s account (ask whoever administers it, giving them your
~/.ssh/id_reds.pub). The host has a lowMaxAuthTries: always name the key andIdentitiesOnly, or ssh is disconnected before it offers the right one.Pull the image, as above.
Get the launcher.
spearneeds only docker, ssh and curl; it opens the tunnel, mounts your state and runs the image. It is in the repository underscripts/docker/, and inside the image;--installcopies it to~/.local/binand writes~/.config/spear/local.confwith the image’s name, so thatspearalone is enough afterwards:$ IMAGE=ghcr.io/smartobjectoriented/spear-reds:<version>-reds $ docker run --rm --entrypoint cat $IMAGE /opt/spear/spear > /tmp/spear $ bash /tmp/spear --install --image $IMAGE
Run it on the corpus you want to work in, by its path under
/corpora. The tunnel to the inference server (port 8010 there, 8082 here) is opened the first time and reused while it lasts; the image prints the corpora it found (29) and the standard it bound, then opens the chat.$ spear --reds <account>@<inference host> --key ~/.ssh/id_reds \ --corpus opencn/opencn-ng --ask $ spear --list # every corpus and its path
What does not change from one run to the next goes in a configuration file rather than on every command line:
~/.config/spear/local.conf(client/local.confwhen the launcher runs from the repository), one shell assignment per line.REDS_HOSTandSPEAR_REDS_KEYthere save the two options above,SPEAR_IMAGEsaves--image. Without the script, the same run by hand:$ ssh -o IdentitiesOnly=yes -i ~/.ssh/id_reds -N -f \ -L 8082:localhost:8010 <account>@<inference host> $ mkdir -p ~/.spear/state $ docker run --rm -it \ --security-opt seccomp=unconfined \ --security-opt apparmor=unconfined \ --security-opt systempaths=unconfined \ --memory 16g --memory-swap 16g --pids-limit 4096 \ -e SPEAR_RESOURCE_CONTROL=delegated \ --network host \ --user "$(id -u):$(id -g)" \ -e SPEAR_API_BASE=http://127.0.0.1:8082/v1 \ -e SPEAR_MODEL_NAME=qwen3 \ -e SPEAR_STATE_DIR=/state -e HOME=/state/home \ -v ~/.spear/state:/state \ -w /corpora/opencn/opencn-ng \ ghcr.io/smartobjectoriented/spear-reds:<version>-reds --ask
The limits and
SPEAR_RESOURCE_CONTROL=delegatedgo together: the harness refuses to run a command that nothing bounds, and in a container Docker is what bounds it (Resource control). The launcher gives the container three quarters of the machine’s memory;SPEAR_CONTAINER_MEMORYin the configuration file names another bound.The paths under
/corporaare those of the building machine, relative to its home:opencn/opencn-ng(andopencn/opencn-ng/linux/usr),soo/so3/so3,soo/so3/doc,sye/sye_sol,pos/pos_sol/so3and so on;spear --listprints them all.Work on your own checkout rather than the baked copy: mount it at the same path, and it shadows the copy while the index keeps serving.
$ spear --reds <account>@<inference host> --key ~/.ssh/id_reds \ --mount ~/opencn/opencn-ng:opencn/opencn-ng --corpus opencn/opencn-ng --ask
The index describes the baked revision; after large changes to your tree,
/reindexinside the session rebuilds its collection into your state volume, on the CPU (minutes for a small tree, an hour for a large one).Open a shell on your own tree instead of starting a session at once: run the launcher from the tree, with no harness argument.
$ cd ~/src/my-checkout && spear SPEAR image, in /corpora/<path of the corpus> corpus <corpus name> spear-chat SPEAR on this tree (--ask, --safe, --auto) claude Claude Code on this tree, with the rules, skills and index of the corpus spear:/corpora/<path of the corpus>$
The current directory is bound into the container. When it is a checkout of one of the image’s corpora, at the same path under your home as the corpus has under
/corpora, it takes the place of the baked tree and keeps its index;--tree <corpus name>says so for a checkout that is elsewhere. Any other directory is bound at its own path: it has no index of its own, gets the rules that apply everywhere, and can search every corpus of the image.Two commands are there:
spear-chatSPEAR, as the steps above start it. It needs a model: the inference host, or a hosted one named in the configuration file, in which case no tunnel is opened.
$ cat ~/.config/spear/local.conf SPEAR_IMAGE=<registry>/spear:<version>-<entity> SPEAR_PROVIDER=anthropic SPEAR_MODEL=<model name> ANTHROPIC_API_KEY=<key>
claudeClaude Code, when the image carries it. It names no model and no key: it asks you to log in with your own account on the first run, and the login stays in your state volume. The rules and skills that apply to the corpus are laid out in the container’s home, never in your tree, and the corpus index is its
spear-corpusMCP server (The index as an MCP server).It works from the knowledge base
spear-chatworks from, and gets it the same way:What a SPEAR request starts from
How Claude Code gets it
the rules of
rules.dthat apply to the corpus, the rules learned with/recall, the corpus’s map, the project’s identity and its build and test commandsrule files in
~/.claude/rules, loaded with every sessionthe skills whose scope covers the corpus
~/.claude/skills, offered by their descriptionthe passages retrieved from the index for the request
printed by a hook on every prompt;
search_corpussearches furtherthe knowledge recorded for the workspace
printed by the same hook;
spear-knowledgelists the records and proposes new onesRetrieval is not left to the model’s choice in either: the hook runs SPEAR’s own search on each prompt.
/memory,/skillsand/mcpshow, inside Claude Code, what a session was given. A prompt is given at most what Claude Code reads in full, some 10 000 characters: the knowledge, then as many passages as fit.From an editor. The container is named
spear-<tree>-<n>. Attach VS Code to it (Dev Containers: Attach to Running Container), open the tree, and install the Claude Code extension in the container. The extension starts its own copy of the program, which reads the same home and the same image-wide hook, so its panel works from the same base as theclaudecommand; what the shell prepared at its start is the corpus of the directory it was opened in.claudein the editor’s terminal is the command above.
An image gains Claude Code as one more layer, once it is built:
$ scripts/docker/add-claude.sh <registry>/spear:<version>-<entity>
Hand your work on as an image. What a session registers, indexes and records stays in your state directory (
~/.spear/state): the corpora added with/corpus add, the index/reindexbuilds, the knowledge you accepted, the skills that were saved and the rules taught with/recall.--buildwrites all of it into a new image, on top of everything the image you run already holds:$ spear --build <registry>/spear:<version>-<name> registry 1 added: <corpus> index <collection> (<n> chunks) knowledge <n> active records skills 1 added: <skill> rules <n> learned built <registry>/spear:<version>-<name>
Both assistants then start from it: a colleague who runs the new image gets these additions in
spear-chatand inclaudealike. Knowledge an assistant only proposed stays behind until you accept it (/knowledge accept <id>inspear-chat).The source trees are not copied. A corpus whose tree is under your home is named by its path relative to it, so whoever runs the new image from a checkout at the same place under their own home, or names it with
--tree, gets its index and picks the work up. A tree that was only opened, never registered, is left out: its index is tied to its path on your machine.
The --ask at the end is the permission mode (spear-chat): confirm each
edit and command. --safe is read-only, --auto runs without asking.
Everything a session accumulates stays in ~/.spear/state on your machine.
1.2.4. Laying out your checkouts
Inside the container every corpus lives under /corpora, at a path
relative to your home directory on the machine that built the image. For
the SO3 family that is soo/so3:
Corpus |
Path under |
Comes from |
|---|---|---|
|
|
the SO3 repository |
|
|
the SO3 repository |
|
|
fetched by the SO3 build |
|
|
vendored in SO3 |
So one clone is enough, wherever you keep it:
$ git clone https://github.com/smartobjectoriented/so3.git ~/soo/so3
and it is mounted with -v ~/soo:/corpora/soo. A tree you do not have is
not an error: the container prints which corpora it found and which it did
not, then works with what is there.
To see the list an image expects, ask it:
$ docker run --rm --entrypoint cat ghcr.io/smartobjectoriented/spear:<version>-public \
/opt/spear/client/projects.json
1.2.5. Running it
$ mkdir -p ~/.spear/state
$ docker run --rm -it \
--security-opt seccomp=unconfined \
--security-opt apparmor=unconfined \
--security-opt systempaths=unconfined \
--memory 2g --memory-swap 2g --pids-limit 256 --cpus 8 \
-e SPEAR_RESOURCE_CONTROL=delegated \
--network host \
--user "$(id -u):$(id -g)" \
-e SPEAR_API_BASE=http://127.0.0.1:8080/v1 \
-e SPEAR_STATE_DIR=/state -e HOME=/state/home \
-e SPEAR_DB_PATH=/state/chromadb \
-v ~/.spear/state:/state \
-v ~/soo:/corpora/soo \
-w /corpora/soo/so3/so3 \
ghcr.io/smartobjectoriented/spear:<version>-public
Each line has a reason:
--security-opt×3Let
bubblewrap, which confines every command, start inside the container; they give it nothing on the host (The three flags that are not optional). Without them the container stops at once and says so.--memory…--cpusandSPEAR_RESOURCE_CONTROL=delegatedEach command’s resource limits are enforced by Docker for the container as a whole, since there is no systemd inside to do it per command. The variable tells the harness so; without it every command fails with
resource control unavailable(Resource control).--network hostandSPEAR_API_BASEThe model endpoint. With host networking
127.0.0.1means your machine, so a server — or an SSH tunnel to one — listening locally is reachable as is.--userand the state volumeConversations, workspace knowledge, the audit trail and — through
SPEAR_DB_PATH— the retrieval index you build are written to~/.spear/stateas you, and survive the container. Without the volume they are lost when it exits.-v ~/soo:/corpora/sooand-wYour checkouts, read-write: the assistant edits files when you ask it to. The working directory picks the corpus the session opens on.
Anything after the image name goes to the harness unchanged, as it would to
spear-chat, e.g. --auto, --fresh or --temp 0.1 (spear-chat).
The launcher’s own backend flags — --reds, --local — do not apply: the
endpoint is SPEAR_API_BASE.
1.2.6. The first session: indexing
A public image carries no retrieval index: an index holds chunks of every tree it was built from, and nothing says those may be redistributed. The first session on a corpus therefore answers without retrieval until you build its index:
/reindex
It runs inside the container with the embedder the image carries, and writes
into /state/chromadb — your state volume — so it is done once per corpus,
not once per run.
On a CPU it takes a while for the larger trees; until then the assistant still
works, by searching the files with its tools instead of the index.
1.2.7. When something is wrong
WARNING: 8 mounted corpora have no collection in the baked indexExpected with a public image, which carries no index: see The first session: indexing. It disappears for each corpus once you have run
/reindexon it.bubblewrap cannot start in this containerOne of the three
--security-optflags is missing.resource control unavailable: systemd-run is absent-e SPEAR_RESOURCE_CONTROL=delegatedis missing, with the limits beside it.Nothing mounted at /corporaThe
-vline is missing or points at an empty directory.missing: so3 soo/so3/so3The tree is not at the expected path; compare with Laying out your checkouts.
- The chat opens but every answer fails
The endpoint is not reachable from the container: check
curl $SPEAR_API_BASE/modelson the host.