# Getting Started

Audience: new users and developers who want a working relurpish workspace. Purpose: from zero to a first completed agent turn. Prerequisites: none; this is the starting doc.

# Prerequisites

# 1. Build

From the repository root:

go build -o relurpish ./app/relurpish
go build -o relurplint ./app/relurplint

In sandboxed or locked-down machines, repo-local Go caches help:

export GOMODCACHE=$PWD/.gomodcache
export GOCACHE=$PWD/.gocache

You can also run without installing: go run ./app/relurpish ....

# 2. Prepare a model backend

The default provider is Ollama with the model gemma4:e4b:

ollama serve                # in its own terminal, if not installed as a service
ollama pull gemma4:e4b

Other backends:

• LM Studio: start the local server (default http://localhost:1234).
• OpenAI-compatible endpoint: set the endpoint in relurpify_cfg/model/provider/openai_compatible.provider.yaml and export RELURPIFY_LLM_API_KEY.
• Offline: no backend needed; see Running offline .

Thinking models are supported; the shipped gemma4 profile arms bounded decision repair for malformed model output.

# 3. Initialize a workspace

A workspace is any project directory you want the agent to work in.

mkdir -p ~/code/my-demo && cd ~/code/my-demo
git init                    # recommended
/path/to/relurpish doctor

On an empty workspace, doctor materializes the starter configuration into relurpify_cfg/:

• workspace.yaml — provider, model, sandbox, logging, postures
• model/provider/ and model/profiles/ — endpoints and per-model behavior
• security/ — sandbox, shell blacklist, tool policies, ingestion rules
• tools/ — 99 tool manifests
• prompts/ — the prompt corpus
• euclo/ — shipped thoughtrecipes plus families.yaml

Doctor never overwrites your edits; --fix explicitly (re)materializes, and --yes applies fixes without prompting. --set-provider <name> switches the provider and re-runs the diagnosis.

Two informational warnings are normal on a healthy machine: runner: missing (the app spawns the runner on first chat) and runtime_image: degraded (set image_digest in relurpify_cfg/security/sandbox.policy.yaml to pin the container image).

# 4. Configure the model

Edit relurpify_cfg/workspace.yaml:

model:
  provider: ollama      # ollama | lmstudio | openai_compatible | offline
  name: gemma4:e4b      # any model your backend serves

The full tree is documented in Configuration . The --inference-model CLI flag only sets a backend default; the workspace model configuration governs agent turns.

# 5. Run

/path/to/relurpish chat

Doctor is the readiness surface; run it any time:

/path/to/relurpish doctor          # human-readable report
/path/to/relurpish status          # script-friendly diagnostics (--format json)

status exits non-zero when the workspace is degraded, so it works as a CI probe.

# Verify the installation

1. relurpish doctor ends with Result: ready.
2. relurpish chat opens with a Postures banner, e.g. Postures — approvals: governed; intent selection: deterministic.
3. Type a read-only ask, for example “list the files in this repository and summarize what it is”. The turn completes without approvals because it performs no writes.

# Environment variables

Parsed only by the configuration boundary; precedence is CLI flag > environment > workspace config > built-in default.

RELURPIFY_STRICT details: five workspace.yaml keys have built-in defaults (paths.state_dir, logging.level, logging.format, audit.retention_days, telemetry.enabled). Unset or 0/false/no/off, missing keys are filled and logged. 1/true/yes/on, a workspace.yaml missing any of them fails loading and names the keys. Any other value is a boot error.

# Running offline

The offline provider is a deterministic scripted model that exercises tool dispatch, streaming, and compilation without a backend, Docker, or network:

relurpish doctor --offline --fix
relurpish chat --offline

It is intended for plumbing checks and CI, not for real coding work.

# Troubleshooting

# Where to go next

• Relurpish guide — daily use: commands, approvals, recipes.
• Configuration — every file in relurpify_cfg/.
• Recipe DSL — author your own workflows.
• Architecture — how the system works under the hood.