Getting started

Prerequisites

You need two things on your machine:

• Python 3.11 or newer
• Docker, installed and running (on macOS, OrbStack works well)

Docker is only needed when you run a session. It is not needed to install the package.

Install

With pip

The package is published to the GitLab package registry of the spens project. The project is public, so no login or token is needed.

pip install spens --extra-index-url https://gitlab.com/api/v4/projects/refwd1%2Fspens/packages/pypi/simple

With uv

uv tool install spens --index https://gitlab.com/api/v4/projects/refwd1%2Fspens/packages/pypi/simple

uv tool install installs spens into its own environment and puts the spens command on your PATH.

Verify

spens list

This prints the available environments and agents.

Update pricing data

The package bundles a snapshot of LLM pricing data, but vendors change prices often and the snapshot can be out of date by the time you install. Fetch the latest published prices so session cost summaries are accurate from the first session:

spens pricing --refresh

This also pre-populates the local cache, so your first session summary is not left to the lazy fallback: spens only re-fetches prices when it computes a summary and finds the cache missing or older than 24 hours, and a fetch that times out or fails falls back to the bundled snapshot. For details, see Pricing.

Configure the workspace

Run this in your project directory:

cd my-project
spens init

spens init asks a short set of questions:

1. What type of stack is used (node, python, dotnet, rust, go, java, manual)
2. Do you want to allow public GET access from the internet
3. Do you want to allow access to common URLs for tooling (package registries and similar, based on your stack)
4. What model provider you are using (fireworks, anthropic, openrouter, openai, manual; you can pick several)
5. Do you want to configure common environment variables for the provider

It then writes a .spens.config.json file with the matching domain rules, key injection rules, and capture URLs, and adds .spens to your .gitignore.

Make sure your provider API key is set in your host environment (for example ANTHROPIC_API_KEY). Spens gives the agent a placeholder value and injects the real key only for approved domains, so the real key never enters the container.

Non-interactive init

You can also run spens init without prompts:

spens init --yes --stack node --provider anthropic

Run an agent

spens node-24 pi .

The format is: spens <environment> <agent> <workspace>.

• The first run builds the Docker images for the environment, the agent, and the interceptor. This takes a few minutes. Later runs reuse the cached images.
• The current directory (.) is mounted as the workspace.
• The pi agent starts in an interactive session.
• When the session ends, you choose whether to keep the agent's file changes or roll the workspace back to its pre-session state.

Yolo mode

You can also give the agent a prompt and let it run unattended:

spens node-24 pi . "explain what this repository does"

The agent executes the prompt and exits. Review the log afterward.

Review the session

spens log-viewer

This opens a local web UI at http://127.0.0.1:7331 with four tabs showing everything the agent did. See Log viewer for details.