Setup

See Quick Start at the top of the README for the fast path.

Synced from Prax at f62d7985 View source ↗

← Guides

Prerequisites

  • Python 3.13 (managed via uv).
  • At least one messaging channel:
    • TeamWork (web UI) — the Slack-like web frontend and the primary channel. Requires the sibling TeamWork app running and TEAMWORK_ENABLED=true (Docker Compose sets this automatically). No external account or ngrok needed. User messages reach Prax over the TeamWork webhook.
    • Discord (text + attachments) — requires a Discord bot token (free). No ngrok needed — connects via WebSocket.
    • Twilio (Voice + SMS) — requires a Twilio account, verified phone number, and ngrok for webhooks (Twilio’s servers must reach Prax from the public internet, which the local Tailscale sidecar can’t provide). Paid per message/minute.
  • Optional, recommended for remote access: Tailscale account + a reusable, non-ephemeral auth key. Lets you reach TeamWork over HTTPS from your laptop without exposing the host’s network or installing tailscaled on the server. See Configuration → Remote access.
  • OpenAI (or alternate LLM) credentials.
  • Java 11+ (for opendataloader-pdf PDF extraction).
  • Docker (for sandbox code execution).
  • Optional: NVIDIA GPU with 8GB+ VRAM + vLLM + Unsloth (for self-improving fine-tuning). To attach a host GPU to the sandbox container for ad-hoc CUDA work (Whisper acceleration, local LLM inference, ML experiments via sandbox_shell), install nvidia-container-toolkit and use make sandbox-gpu (or layer the override in via COMPOSE_FILE=docker-compose.yml:docker-compose.gpu.yml in .env). See Sandbox → GPU access for details.
  • Optional: Playwright (pip install playwright && playwright install chromium) for browser automation.
  • Optional: gh CLI (for self-modification PR creation).

Installation Details

See Quick Start at the top of the README for the fast path.

Sandbox code execution requires both Docker Desktop running and the sandbox image built. The sandbox lives in the sibling prax-sandbox repo — build it with cd ../prax-sandbox && make build (docker-compose builds it for you). Without the image, sandbox tools fail with a “pull access denied” error — it’s a local image, not on Docker Hub. If Docker isn’t running, the agent falls back to saving source files to the workspace. See Providing Prax a sandbox (incl. remote mode).

Browser automation requires Playwright: uv run playwright install chromium

On startup you’ll see:

Starting Prax — provider=openai model=gpt-5.4-nano temperature=0.7 encoding=o200k_base

Required Configuration

These .env settings are required for Docker Compose deployments:

Variable Purpose
OPENAI_KEY or ANTHROPIC_KEY At least one LLM provider API key
PRAX_USER_ID Your workspace directory name (e.g. usr_alice). The sandbox mounts only this folder for user isolation. Pick any slug — Prax creates the directory and associates it with your identity on first run. Prax refuses to start without this.

Memory System Setup

Prax has a two-layer memory system. Short-term memory (STM) works out of the box with no extra infrastructure. Long-term memory (LTM) requires Qdrant and Neo4j.

Enabling Long-Term Memory

# Start core services + memory infrastructure
docker compose --profile memory up --build

Then set in .env:

MEMORY_ENABLED=true

This starts Qdrant (vector store, port 6333) and Neo4j (knowledge graph, port 7474/7687).

Choosing an Embedding Provider

Memory search quality depends on embeddings — numerical representations of text used for similarity matching. You have three choices:

Option 1: OpenAI (default) — Highest quality, easiest setup. Your memory text is sent to OpenAI’s API for embedding. If you’re already using OpenAI for LLM calls, this is the simplest path.

EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small

Option 2: Ollama (local) — No data leaves your machine. Good quality. Requires running Ollama (included in Docker Compose).

# Start with Ollama
docker compose --profile memory --profile ollama up --build

# Pull the embedding model (one-time)
docker compose exec ollama ollama pull nomic-embed-text

EMBEDDING_PROVIDER=ollama
EMBEDDING_MODEL=nomic-embed-text
OLLAMA_BASE_URL=http://localhost:11434

Option 3: fastembed (in-process) — Zero infrastructure, runs inside the Prax process. Lower quality but simplest possible setup.

EMBEDDING_PROVIDER=local

See Memory documentation for a detailed comparison of quality, speed, cost, and privacy trade-offs.

Verifying Memory

After starting with memory enabled, you can verify it’s working: