Getting Started

Best Practices

Practical guidance for getting reliable results from SITU — from model selection and mount scope to context management and mode discipline.

Mount only what the agent needs

The MOUNTPOINT setting controls what the agent can read and write. Mounting $HOME or / is convenient but gives the agent access to credentials, configs, and unrelated projects. Set MOUNTPOINT to the specific project root the agent is working on: 

MOUNTPOINT=/projects/my-service

Smaller mount scopes also reduce the risk of accidental writes to unrelated files during agentic operations.

Stay in RESTRICTED mode by default

RESTRICTED mode (--network=none) is the default for a reason — it is the only configuration where network exfiltration is physically impossible, not merely unlikely. Switch to NETWORK mode only when the task genuinely requires it (fetching a dependency, querying a remote API), and switch back when it does not.

Pick the right model for your hardware

A model that saturates RAM or causes excessive swapping produces slow, degraded results. As a starting point:

Prefer higher quantization (Q6, Q8) over larger parameter counts if quality matters more than speed. Drop any GGUF file into ~/.situ/models/ and update MODEL in situ.conf to swap models without rebuilding anything.

Set a context window you can actually afford

CTX_SIZE defaults to 64 000 tokens. Larger contexts let the agent hold more code in view at once but consume proportionally more memory. For most single-file or small-codebase tasks, 16 000–32 000 tokens is sufficient and leaves headroom for the model weights: 

CTX_SIZE=32000

Raise it when the agent needs to reason across large files or many files at once. Lower it if the sidecar runs out of memory at startup.

Increase the Podman machine memory on macOS

On macOS, Podman runs inside a VM with a fixed memory cap. The default is often 2 GB — far too small for any useful model. Set it before the first run and size it to cover model weights plus overhead: 

$ podman machine stop
$ podman machine set --memory 16384
$ podman machine start

See Tuning for more detail.

Verify isolation before a sensitive session

Run the built-in probe before starting a session with confidential code: 

$ situ -t

All external HTTP, HTTPS, DNS, and TCP probes should show [PASSED]. If any fail, do not proceed until the cause is understood. See Restricted Mode for what each probe tests.

Related