Documentation
Everything you need to set up, connect, and get the most out of Praes.
Quick Start
Get from zero to live telemetry in under five minutes.
Create your account
Sign up with Google or GitHub OAuth. You'll land on the agent creation page automatically.
Create an agent
Give your agent a name and slug. Praes generates an ingestion key automatically. You can configure telemetry mode, retention period, and whether to store raw events.
Install and run praes-connect
Copy your ingestion key from the Console tab, then run:
npx praes-connect --key pk_your_key_here --url https://your-praes-url.vercel.appStart your OpenClaw agent
Run your agent as usual. praes-connect watches your OpenClaw session files and forwards activity, tool calls, costs, SOUL.md, and MEMORY.md to Praes in real time.
praes-connect CLI
The praes-connect CLI is the bridge between your OpenClaw agent and the Praes dashboard. It runs locally alongside your agent and automatically forwards telemetry.
Installation
No install required. Run directly with npx. Requires Node.js 18+.
npx praes-connect --key <your-key>Options
| --key <key> | Required | Your agent's ingestion key from the Console tab |
| --url <url> | Optional | Praes server URL. Defaults to http://localhost:3000 |
| --help | Optional | Show usage information |
What it does
On startup, praes-connect verifies your key against the Praes API, resolves your OpenClaw workspace at ~/.openclaw/workspace, syncs SOUL.md and MEMORY.md, then watches session files for new activity. It sends heartbeats every 5 seconds and gracefully disconnects on SIGINT/SIGTERM.
Workspace resolution
praes-connect looks for your OpenClaw config at ~/.openclaw/openclaw.json to find a custom workspace path. If none is set, it defaults to ~/.openclaw/workspace.
Agent Management
Agents are the core entity in Praes. Each agent has its own ingestion key, telemetry settings, and data isolation.
Creating an agent
Navigate to the Agents page and click "New agent". Provide a name (display name) and slug (URL-friendly identifier). The slug must be unique across your account.
Agent settings
| Telemetry mode | balanced / full / minimal | Controls how much data is collected |
| Retention days | 7 / 14 / 30 / 60 / 90 | How long run data is kept |
| Allow raw events | true / false | Whether to store full event payloads |
Ingestion key
Each agent has a unique ingestion key (prefixed pk_). You can copy it from the Console tab. If you suspect a key has been compromised, rotate it. This invalidates the old key immediately.
Activity & Runs
The Activity page shows all runs for the selected agent, ordered by most recent. Each run represents one conversation turn or task execution.
Run statuses
| running | Blue | Currently processing |
| success | Green | Completed without errors |
| error | Red | Completed with one or more errors |
Run detail
Click any run to view its receipt (summary stats) and full trace timeline. The timeline shows every LLM call, tool call, memory write, and error in chronological order.
Filtering
Use the filter bar to narrow runs by status, channel (telegram, api, slack, etc.), model, or date range. The search also supports run ID lookups.
Memory Vault
The Memory Vault is a three-pane editor for managing your agent's memories. Memories can be created manually or synced from MEMORY.md via praes-connect.
Layout
Left pane: filter sidebar (All / Archived + tag filters). Middle pane: memory list with search. Right pane: content editor with autosave, tags, and provenance info.
Pin & archive
Pin important memories to keep them at the top of the list. Archive stale memories to hide them from the default view without deleting. Both actions are reversible.
Tags
Add tags to organize memories. Tags are color-coded and filterable from the sidebar. Type a tag name and press Enter to add it. Click the X to remove.
Provenance
Memories created by praes-connect include provenance metadata: which run created them, which channel, and which tool. Manually created memories don't have provenance.
Soul Editor
The Soul page displays your agent's structured identity, synced from SOUL.md. Each section maps to a field in the soul record.
Sections
| Purpose | ## Purpose or ## Mission | What your agent does |
| Principles | ## Principles | Core behavioral rules |
| Tone | ## Tone | Communication style |
| Do's | ## Do's | Encouraged behaviors |
| Don'ts | ## Don'ts | Prohibited behaviors |
| Tool Policy | ## Tool Policy or ## Tools | When and how to use tools |
| Escalation | ## Escalation | When to escalate to a human |
| Output Format | ## Output Format | Response formatting rules |
| Privacy | ## Privacy | Data handling policies |
Syncing
praes-connect watches SOUL.md for changes and POSTs the content to /api/agents/{slug}/sync. The server parses markdown headings and maps them to soul fields. You can also edit fields directly in the dashboard.
Cost Analytics
The Costs page aggregates spend across all runs for the selected agent.
Stat cards
Top-level cards show total spend, average cost per run, total tokens, and run count. Values update as new runs complete.
Breakdown
Toggle between breakdowns by model, provider, or time period. Each entry shows the model/provider name, run count, token totals, and spend.
Tool Registry
Tools are auto-discovered from agent activity. Every time your agent calls a tool, Praes creates or updates the tool entry.
Tool metadata
| Name | Auto-detected | The tool name from the event payload |
| Status | active / inactive / error | Based on error rate threshold (>50%) |
| Total calls | Counter | Lifetime invocations |
| Error count | Counter | Lifetime failures |
| Recent errors | Last 5 | Most recent error messages |
| Last used | Timestamp | When the tool was last called |
Ingest API
The ingest API receives events from praes-connect. It's designed for high-throughput event streaming.
Endpoint
POST /api/ingest
Authorization: Bearer <ingestion-key>
Content-Type: application/jsonPayload
{
"events": [
{
"id": "evt_abc123",
"type": "llm_call",
"runId": "run_xyz789",
"timestamp": "2025-01-15T10:30:00Z",
"data": {
"model": "gpt-4o",
"provider": "openai",
"tokensIn": 1500,
"tokensOut": 800,
"cost": 0.0124
}
}
],
"sequenceNumber": 42
}Event types
| heartbeat | Connector health check (not stored as event) | |
| run_started | Creates a new run record | |
| run_finished | Marks run as success/error, calculates duration | |
| llm_call | LLM invocation with model, tokens, cost | |
| tool_call | Tool invocation with name, status, duration | |
| memory_write | Agent wrote to memory | |
| error | Error occurred during the run | |
Security
Praes uses Supabase with row-level security. Every query is scoped to the authenticated user.
Authentication
OAuth via Google or GitHub. Sessions are managed with secure HTTP-only cookies via Supabase SSR.
Data isolation
RLS policies ensure you can only access agents you own and their associated runs, events, memories, tools, and soul data. The admin client (used only by the ingest API) bypasses RLS for event insertion.
Ingestion key security
Ingestion keys authenticate the praes-connect CLI to the ingest and sync APIs. They don't grant access to the dashboard. Rotate keys immediately if compromised.
Need help?
Something not working? Have a feature request?