Skip to content

New User Walkthrough (10 minutes)

This walkthrough is a “sanity check” you can run after installing RexOS. You’ll verify:

  • your local model (Ollama) works
  • tools are sandboxed to a workspace
  • memory persists across runs
  • harness workspaces create durable artifacts + git checkpoints

0) Prerequisites

  • rexos is installed and on your PATH
  • Ollama is running: ollama serve
  • you have at least one chat model available:
1
ollama list

If the default model (llama3.2) is not installed, either pull it:

1
ollama pull llama3.2

…or edit ~/.rexos/config.toml and set:

1
2
[providers.ollama]
default_model = "qwen3:4b" # example: pick a model you already have

1) Initialize RexOS

1
rexos init

Expected artifacts:

  • ~/.rexos/config.toml
  • ~/.rexos/rexos.db

2) Run a one-shot agent session (workspace sandbox)

1
2
3
mkdir -p rexos-demo
rexos agent run --workspace rexos-demo --prompt "Create hello.txt with the word hi"
cat rexos-demo/hello.txt

1
2
3
mkdir rexos-demo
rexos agent run --workspace rexos-demo --prompt "Create hello.txt with the word hi"
Get-Content .\rexos-demo\hello.txt

Expected:

  • hello.txt exists in the workspace and contains hi
  • RexOS prints a session_id to stderr (save it for the next step)

3) Re-run with the same session id (memory)

Replace <SESSION_ID> with the id RexOS printed previously.

1
rexos agent run --workspace rexos-demo --session <SESSION_ID> --prompt "Append a newline + bye to hello.txt"

Verify the file updated:

1
cat rexos-demo/hello.txt

1
Get-Content .\rexos-demo\hello.txt

4) Create a harness workspace (durable artifacts + git)

1
2
mkdir -p rexos-harness-demo
rexos harness init rexos-harness-demo

1
2
mkdir rexos-harness-demo
rexos harness init rexos-harness-demo

Expected files in rexos-harness-demo/:

  • features.json
  • rexos-progress.md
  • init.sh and init.ps1
  • a .git/ directory with an initial commit

Run the harness preflight (no prompt):

1
rexos harness run rexos-harness-demo

5) Docs buttons (reproducibility)

On the docs site, every page should have:

  • Edit this page → opens GitHub at docs-site/...
  • View source → opens the raw Markdown file

If these buttons are missing or broken, check the docs workflow and mkdocs.yml (repo_url + edit_uri).