First Steps

Installation

Seven steps from a fresh machine to a running, isolated agent: install Podman or Docker, clone the repository into ~/.situ/, build the container, download a local model, probe the network isolation, run a test query, and add a shell alias.

0. Prerequisite — Podman 4+ or Docker

SITU uses Podman or Docker as its container engine. The containers are created on session start and destroyed on exit; no service is left running between sessions. Podman is recommended — it runs rootless by default and needs no daemon. Docker works equally well if you already have it installed.

Check whether Podman is already installed:

$ podman --version

If it is missing, install it from podman.io/docs/installation. To use Docker instead, set CONTAINER_ENGINE=docker in situ.conf.

1. Clone the repository

SITU lives in ~/.situ/. Create that directory and clone the repository into it: 

$ mkdir ~/.situ/ && cd $_
$ git clone https://github.com/ndburn/SITU-Agent .

2. Build the SITU container

Run the build script from the cloned repository:

$ ~/.situ/scripts/build.sh

This builds the container image. Nothing is installed on the machine beyond the image itself.

3. Download a model

SITU runs against a local GGUF model. Any GGUF will work — the example below uses Gemma4-E4B (Q4_K_M), which is small enough to run on modest hardware and good enough to be useful for code work: 

$ mkdir -p ~/.situ/models && \
    curl -L --output-dir ~/.situ/models -O \
    "https://huggingface.co/lmstudio-community/gemma-4-E4B-it-GGUF/resolve/main/gemma-4-E4B-it-Q4_K_M.gguf"

Larger models (more parameters, higher quantization) produce better code at the cost of memory and inference speed. Drop any other GGUF into ~/.situ/models/ and reference it from the config to swap models.

4. Probe the network isolation

Before running a real query, verify that the pod's network isolation is in place. The script runs a series of connectivity probes from inside a live pod: 

$ ~/.situ/scripts/situ.sh -t

Expected output:

SITU v0.4.0

Config    : /home/user/.situ/scripts/../situ.conf
LM server : POD  (llama.cpp official image)
Model     : gemma-4-E4B-it-Q4_K_M.gguf
Ctx size  : 64000
Mountpoint: /home/nd/.situ
Mode      : RESTRICTED

  Connected
[PASSED] LM server is reachable     http://127.0.0.1:8080/v1/models
[INFO]   Model in use               gemma-4-E4B-it-Q4_K_M.gguf
[PASSED] External HTTP is blocked   http://example.com
[PASSED] External HTTPS is blocked  https://example.com
[PASSED] External DNS is blocked    example.com
[PASSED] External TCP is blocked    8.8.8.8:53

Each probe is logged: the local model is reachable, every external HTTP / HTTPS / DNS / outbound TCP path is blocked. See Restricted Mode for what is being tested and why.

5. Run a test query

Run a non-interactive single query to confirm everything is wired up end-to-end:

$ ~/.situ/scripts/situ.sh -p "Who was Albert Einstein?"

The pod is created, the model is loaded, and the answer is printed to standard output. On exit the pod is destroyed.

Next

The default mode is RESTRICTED. To understand exactly what that means at the kernel level — and when (and how) to switch into NETWORK mode — read Restricted Mode and Network Mode.

6. Create a shell alias

Typing the full script path is tedious. Add an alias to the shell (MacOS: ~/.zshrc, most Linux distributions: ~/.bashrc) 

alias situ=~/.situ/scripts/situ.sh

Reload the shell, and from then on for the interactive session run:

$ situ

Related