Start Here

Operator Journey

A single recommended path for new operators: install, configure, validate, and run safely.

1. Install + bootstrap: run wrenos init and generate baseline config.
2. Safety checks: run wrenos doctor and resolve all red diagnostics.
3. Runtime verification: run wrenos status and confirm paper-first execution posture.
4. Configuration hardening: set required env/config values and re-run checks.
5. Launch readiness: validate against the release checklist and regression artifacts before production tags.

WrenOS Documentation

WrenOS Documentation

The open-source control plane for operator-managed crypto agent systems.

Explore the Docs

Docs content synced against wrensignal/wrenOS@a73300c.

View on GitHub →

Getting Started

Quick Start

Install WrenOS, initialize an agent profile, and verify your local stack in minutes.

Prerequisites

• Node.js 20+ and npm
• OpenClaw runtime access
• A Solana wallet for eventual live execution (paper mode is default)

Install and initialize

git clone https://github.com/wrensignal/wrenOS.git
cd wrenOS
npm install
node packages/cli/src/index.mjs init --profile research-agent
node packages/cli/src/index.mjs doctor
node packages/cli/src/index.mjs status

What init does

Creates project config, wires defaults, and scaffolds MCP definitions for research, tool access, and execution context. If .mcp.json is missing, it generates one.

Next steps

Getting Started

Safety Posture

Operational safeguards for agent-managed strategy systems.

Paper-first by default

WrenOS starts with simulation mode enabled. The system records strategy decisions and execution intent without committing capital, giving operators a full audit trail before live risk.

Approval model

External side effects can require explicit approvals based on policy. This keeps execution deliberate and reviewable as confidence changes.

Custody separation

WrenOS does not require custody of private keys. Signing remains in your wallet boundary while agents handle analysis, scoring, and execution decisions.

Degrade safely

Confidence tiers can tighten or suspend execution as data quality deteriorates, reducing impulsive behavior in uncertain states.

CLI

CLI Overview

Core command surface for setup, diagnostics, runtime checks, and configuration.

Command model

The CLI is designed around initialization, verification, and controlled iteration. Commands are composable and readable, with explicit naming for operator clarity.

Common commands

# initialize a profile
wrenos init --profile research-agent

# run health checks
wrenos doctor
wrenos status

# inspect/set config
wrenos config list
wrenos config set liveExecution false

wrenos init

Bootstraps project configuration and writes default runtime artifacts.

wrenos doctor

Runs diagnostics for dependency health, connectivity, and required runtime components.

wrenos status

Returns current profile, routing state, and execution posture.

wrenos config

Reads and updates config keys for inference, execution, and policy controls.

wrenos start

Starts the configured runtime loop for your selected profile.

Getting Started

Configuration

WrenOS uses inspectable JSON config under .wrenos/config.json (legacy .0xclaw/config.json fallback remains temporary).

Config priority

Runtime reads .wrenos/config.json first. If missing, it can read the legacy path and emits a migration warning. For fresh setups, always use .wrenos/.

Common keys

Set values from CLI

wrenos config set liveExecution false
wrenos config set inference.baseUrl https://your-openai-compatible-endpoint.example
wrenos config set execution.venues.jupiter.enabled true

CLI

wrenos init

Initialize WrenOS with a profile and write safe defaults.

Usage

wrenos init --profile research-agent

What it does

• Creates .wrenos/config.json from profile templates.
• Sets liveExecution: false by default.
• Generates .mcp.json if missing.

CLI

wrenos doctor

Run environment and configuration diagnostics.

Checks include

• Node runtime compatibility
• Config presence/profile validity
• MCP config availability
• Inference route readiness
• Execution mode + paper-safe default

CLI

wrenos status

Snapshot current profile, safety posture, and runtime-facing config.

Purpose

Use status to confirm selected profile, execution mode, and critical route values before running loops or enabling any external action path.

CLI

wrenos config

Read and mutate nested config keys using dot-path syntax.

Usage

wrenos config set risk.maxTradeUsd 25
wrenos config set loop.heartbeatAdaptive true
wrenos config set inference.routes.research deepseek-v3.2

CLI

wrenos start

Beta orchestration loop for structured heartbeat operations.

Current status

wrenos start is available but still beta. Prefer deterministic checks with wrenos start --once and supervise long-running production loops with your scheduler/process manager.

Packages

Core

@wrenos/core — policy defaults, safety primitives, and shared utilities.

Role

Core centralizes reusable control-plane behaviors and safety defaults so profile and adapter layers share consistent policy semantics.

Packages

Profiles

@wrenos/profiles — paper-first, safety-first profile templates.

Shipped templates

• research-agent
• research-only
• solo-trader-paper
• trading-agent-paper
• trading-agent-live-disabled
• meme-discovery-research
• meme-discovery-trading-paper

Packages

Loops

@wrenos/loops — heartbeat planning and validation summaries.

Role

Loop primitives govern cadence and condition-aware behavior, helping operators degrade safely as data quality or route health changes.

Packages

Adapters

@wrenos/adapters — connectors for inference, execution, and operator interfaces.

Adapter scope

• Inference: OpenAI-compatible request shape (private route optional)
• Execution: Jupiter + pump.fun paths
• Operator UX: chat/operator surfaces

Packages

Private Inference (Optional)

OpenAI-compatible private-route SDK support (Speakeasy optional, not required for v1 baseline).

Install

npm install speakeasy-ai

What it handles

• Initial request
• 402 challenge parsing
• EIP-712/EIP-3009 signing
• Replay with payment proof headers
• JSON/SSE streaming output

Packs

Meme Discovery

Dual-agent meme discovery workflow with composite scoring.

Init

wrenos init-pack --pack meme-discovery

Includes

• Research + trading agent configs
• Watchlist handoff schema (inbox/meme-watchlist-*.json)
• Composite weighted scoring defaults
• Jupiter + pump.fun adapter wiring

Packs

Research Agent (Dual Agent Pack)

Bare-bones two-agent operating model for research-to-trading handoff.

Components

• research-agent for evidence briefs
• trading-agent for validation and risk-gated execution posture
• handoff schema at handoff/research-brief.schema.json

Guides

Private Inference (Optional)

Optional private inference routing with explicit fallback posture.

Baseline env

• OPENAI_BASE_URL (or default route)
• SPEAKEASY_API_KEY (deployment-dependent)
• route envs/overrides as needed

Operational guardrails

• Cache deterministic calls where possible
• Gate expensive calls on material input deltas
• Track per-cycle model usage and cost
• Report degraded route state explicitly

Guides

Railway Deploy

Template deploy for a full WrenOS stack with paper-first defaults.

Required env

• PROFILE
• OPENAI_BASE_URL (or default route)
• OPENCLAW_API_KEY
• TELEGRAM_BOT_TOKEN (for chat UX)

Post-deploy verification

1. Service health and restart stability
2. Inference connectivity and route checks
3. Profile + execution mode sanity
4. Heartbeat/log artifact verification

Guides

Migrating from 0xClaw

Move to WrenOS naming and config paths with minimal disruption.

Key changes

• Repo: wrensignal/0xClaw → wrensignal/wrenOS
• CLI: 0xclaw → wrenos
• Config: .0xclaw/ → .wrenos/

Recommended migration

wrenos migrate
wrenos doctor && wrenos status

Guides

Docs Parity Matrix

Section-by-section parity map between wrenos.ai/docs and source markdown in wrensignal/wrenOS.

Reviewer checklist

• Every major docs section links to a concrete source markdown path.
• No claim contradicts current CLI/runtime behavior.
• Command snippets match current command names and flags.
• Safety defaults remain paper-first and opt-in for live execution.

Reference

Architecture

Composable control plane: profiles, adapters, loops, and operator governance.

Three-layer model

1. Open-source control plane (CLI, profiles, packs, loops, adapters)
2. Hosted runtime infrastructure (optional/default path)
3. Operator workflows and governance (approvals, runbooks, audits)

Runtime flow

Inference path: agent loop → adapter → default inference route (optional private route supported).

Execution path: decision → execution adapter → venue quote/build → paper/live policy gate.

Reference

Runtime Status

Current maturity snapshot from the repository docs.

Usable today

• CLI lifecycle: init, doctor, status, config, wallet, test, start, init-pack, bootstrap-wrenos
• Profile templates with paper-mode defaults
• Inference connectivity tests and execution path tests
• Inspectable file-based configuration and output artifacts

Experimental

• wrenos start beta orchestration loop
• Turnkey Telegram operator stack as a production-default path
• Expanded pack ecosystems and auto-wiring assumptions

Reference

Config Schema

Representative schema derived from shipped profile templates.

Example profile JSON

{
  "profile": "trading-agent-paper",
  "liveExecution": false,
  "loop": { "enabled": true, "heartbeatAdaptive": true, "tradeExecution": "paper" },
  "risk": { "maxTradeUsd": 25, "maxDailyNotionalUsd": 75 },
  "inference": {
    "provider": "openai-compatible",
    "baseUrl": "https://your-openai-compatible-endpoint.example",
    "routes": {
      "research": "deepseek-v3.2",
      "deep_think": "qwen3-235b-a22b-thinking-2507",
      "codegen": "qwen3-coder-480b-a35b-instruct",
      "uncensored": "venice-uncensored"
    }
  }
}

Reference

Changelog

Recent release history.

2026-03-07 — Rebrand: 0xClaw → WrenOS

• Primary CLI renamed to wrenos
• Primary config directory renamed to .wrenos/
• Workspace package scope moved to @wrenos/*

Compatibility aliases remain temporarily (0xclaw, legacy config fallback, bootstrap aliases), with planned removal target v0.3.0.