1.3. Installation
There are two ways to run SPEAR. Which one you want depends on whether you intend to use it or to change it.
1.3.1. Prerequisites
Requirement |
Note |
|---|---|
Linux with systemd |
the execution harness places each tool call in a transient user scope; without a user manager it cannot apply resource control |
Python 3.12 or later |
the client runs from its own virtualenv under |
An inference endpoint |
local, remote or hosted — see Model backends |
|
the sandbox layer for untrusted commands |
Docker (container path only) |
run with the security options the harness requires (Container) |
A GPU is a property of the backend, not of the client. The client itself is undemanding; a machine that cannot serve a model can still run SPEAR against one that can.
1.3.2. Native installation
This is the path to take if you will modify the platform, re-index a corpus or register a project.
$ git clone https://github.com/smartobjectoriented/spear ~/spear
$ cd ~/spear
$ client/deploy/install.sh
The installer creates the virtualenv under client/, installs PyTorch and the
client requirements from client/deploy/requirements.txt, and caches the
active embedding model. It is idempotent. Check what the harness needs before
first use:
$ client/deploy/preflight.sh
On Ubuntu 24.04 and later, unprivileged user namespaces are restricted by
AppArmor and bwrap cannot start; sudo client/deploy/enable-sandbox.sh
installs the profile that allows it.
The launcher is client/spear-chat.sh; putting it on your PATH as
spear-chat is the usual arrangement.
Note
The virtualenv records its own absolute path, so the tree cannot simply be moved. Re-run the installer after relocating it.
1.3.3. Container installation
If you have an inference endpoint and only want to use SPEAR, Docker is enough:
$ git clone https://github.com/smartobjectoriented/spear ~/spear
$ cd ~/spear
$ scripts/docker/build.sh # spear:<version>-public
The build takes a while, mostly for the embedding model.
Running the images shows how to run the image, including the security
options without which the harness refuses to run any command. Without
--profile the build produces the public image; --profile private
builds the one scripts/docker/spear-docker.sh runs on a workstation that
also has the native installation, and --profile reds the one handed to
the institute, cut to the corpora it bakes (Three profiles).
1.3.4. The inference runtime
The client does not build or download a model. Where you also serve the model on this machine, the runtime is reconstructed from a pinned manifest rather than from whatever is current:
$ scripts/bootstrap-runtime.sh --root ~/spear-runtime --dry-run
$ scripts/bootstrap-runtime.sh --root ~/spear-runtime
$ scripts/bootstrap-runtime.sh --root ~/spear-runtime --verify
Every version installed comes from server/runtime/manifest.json: an
immutable upstream commit, exact model shards with their publisher’s hashes,
and a tested constraints file. There is no “latest” and no branch name — a
moving reference would mean the binary serving today differs from the one that
was measured, with nothing recording the change.
1.3.5. What ends up where
Path |
Holds |
|---|---|
|
the client: chat, agent runtime, retrieval, execution harness |
|
the inference server component |
|
this documentation |
|
the container image: |
|
the operator scripts: |
|
the corpus registry for this machine (untracked) |
|
machine-specific settings (untracked), written by |
|
the external capabilities (MCP providers) of this machine
(untracked, optional; |
|
everything a session accumulates; its contents and defaults are in Directory layout |
The untracked files are the boundary between the platform and the machine. Nothing machine-specific belongs in a tracked file — see Configuration reference.
machine.env is not written by hand. From the repository root:
$ . ./env.sh # puts scripts/ on PATH
$ spear-configure # writes client/machine.env
$ spear-configure --check # does it still match this machine?
It finds the state directory, a spear-private/ tree beside the checkout,
and the embedding host with the model revision both ends’ caches agree on —
refusing to pin one they disagree on. A differing file is shown as a diff and
replaced only on confirmation, kept as machine.env.bak; settings added
below its local-additions marker survive regeneration.
1.3.6. Checking the installation
$ client/spear-chat.sh --help # the CLI, its flags and its settings
The test suite runs offline; Testing gives the commands.
See also