2.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.

2.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 `client/`
An inference endpoint	local, remote or hosted — see Model backends
`bubblewrap`	the sandbox layer for untrusted commands
Docker (container path only)	with the three `--security-opt` flags the harness requires

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.

2.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.

2.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

The build takes a while, mostly for the embedding model. See Container for what the image carries, what it expects mounted, and the three security options without which the harness refuses to run any command. Without --profile it builds the public image; --profile private builds the one spear-docker.sh runs on this machine.

2.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.

2.3.5. What ends up where

Path	Holds
`client/`	the client: chat, agent runtime, retrieval, execution harness
`server/`	the inference server component
`doc/`	this documentation
`docker/`	the container image: `Dockerfile` and entrypoint
`scripts/`	the operator scripts: `spear-configure`, `spear-image`, the container build and launcher under `scripts/docker/`, the version helper
`client/projects.json`	the corpus registry for this machine (untracked)
`client/machine.env`	machine-specific settings (untracked), written by `spear-configure`
`client/capabilities.json`	the external capabilities (MCP providers) of this machine (untracked, optional; `SPEAR_CAPABILITIES_FILE` moves it)
`$SPEAR_STATE_DIR`	everything a session accumulates — history, audit trail, workspace knowledge (`knowledge.sqlite3`), ingested standards; `spear-configure` sets it to `~/.local/state/spear`, and without it the harness falls back to `client/`

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.

2.3.6. Checking the installation

$ client/spear-chat.sh --help          # the CLI, its flags and its settings
$ cd spear && PYTHONPATH=. ./bin/python -m unittest discover -s tests

The suite runs offline and takes a few minutes (Testing).