Skip to content

getting-started.md

Latest commit

 

History

History
112 lines (83 loc) · 3.64 KB

getting-started.md

File metadata and controls

112 lines (83 loc) · 3.64 KB
Raw

Getting Started

This guide starts a local Strata deployment, checks health, and shows how an agent should prepare to read or write memory.

Prerequisites

  • Python 3.9 or newer.
  • A shell with access to the repository checkout.
  • Optional: Docker or a compatible container runtime for container deployments.
  • Optional: SSH access to a remote host if the service runs on another machine.

No LLM provider key is required by the server.

Install from source

git clone https://github.com/rx6ru/strata.git
cd strata
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
strata --help

If packaging files are not installed in your local checkout, use source mode:

PYTHONPATH=. python -m strata --help

Choose non-secret runtime values

Pick values at runtime; do not hardcode them into the skill or repository.

Value Example placeholder Secret? Notes
Data root <data-root> No Directory that stores canonical data and runtime locks.
Gateway URL <gateway-url> No Usually http://127.0.0.1:8787 from the host or SSH tunnel.
Namespace <organization>/<project>/<workstream>/<artifact-type> No Must be exact and lowercase.
SSH target <ssh-target-or-alias> No by itself Use an SSH config alias; do not store private keys in memory.
Hindsight URL <hindsight-url> No by itself Optional derived recall endpoint; no provider key belongs in memory.

Start locally

mkdir -p /tmp/strata-demo
PYTHONPATH=. python -m strata serve \
  --root /tmp/strata-demo \
  --host 127.0.0.1 \
  --port 8787

In another shell:

curl -fsS http://127.0.0.1:8787/healthz
curl -fsS -H 'X-Strata-Client: 1' \
  http://127.0.0.1:8787/v1/policy
curl -fsS -H 'X-Strata-Client: 1' \
  http://127.0.0.1:8787/v1/status

Prepare agent context

Use an exact namespace and current task. Derived recall is optional and must be treated as navigation only.

PYTHONPATH=. python -m strata context \
  --gateway-url http://127.0.0.1:8787 \
  --namespace team/example/research/finding \
  --task "summarize verified Strata setup findings" \
  --max-records 8 \
  --max-chars 24000 \
  --no-recall

The response includes policy hash, canonical root hash, bounded canonical records, and hard instructions for the agent.

Prepare a verified capture

PYTHONPATH=. python -m strata template \
  --gateway-url http://127.0.0.1:8787 \
  --namespace team/example/research/finding \
  --task "record a verified setup observation" \
  --workflow-kind finding

Fill the returned candidate template only after verifying the claim against local files, canonical records, or immutable external evidence. Run capture without --commit first; add --commit only when the dry run is accepted.

Container deployment

When compose.yaml is present, check the configuration before starting it:

./scripts/configure.sh
docker compose --env-file .env config
./scripts/control.sh start
curl -fsS http://127.0.0.1:8787/healthz

The generated .env is local and ignored by Git. It contains runtime paths, numeric UID/GID, loopback binding, and pinned image coordinates, not credentials. Stop the stack without deleting volumes or canonical data using ./scripts/control.sh stop.

If Docker is unavailable, run the Python service directly or use a process manager such as systemd with the same CLI arguments.

Next steps