rtxclaw.ai

Run it now: git clone … && cd rtxclaw && ./rtxclaw — the launcher creates .venv/, installs dependencies, and starts the TUI. Or pip install rtxclaw && rtxclaw — the first-run wizard walks you through the LLM endpoint and model choice.

Install

pip install rtxclaw

That puts a rtxclaw command on your PATH. Run it once with no arguments — the first-run wizard walks you through the LLM endpoint, model, and (optionally) Telegram, then brings the gateway up itself. Three steps and you're in the TUI:

pip install rtxclaw → rtxclaw → answer the wizard → done.

Optional extras:

From a clone (for development)

git clone … && cd rtxclaw && ./rtxclaw — the launcher creates .venv/, runs an editable pip install -e ., and starts the TUI.

Run the gateway, orchestrator and WebUI together

pip install "rtxclaw[web]"     # the WebUI lives in the [web] extra
python -m rtxclaw.serve        # foreground: Ctrl+C stops the whole stack

serve brings all three components up and prints one line per component:

START orchestrator 8099 pid=1234 http=200
START gateway 8100 pid=1235 http=200
START web 8110 pid=1236 http=200
WebUI http://127.0.0.1:8110  (Ctrl+C stops the stack; --detach keeps it running after this shell exits)

python -m rtxclaw.serve --detach   # background; survives the shell closing
python -m rtxclaw.serve status     # one PASS/FAIL line per component
python -m rtxclaw.serve stop       # shut the stack down
python -m rtxclaw.serve --no-web   # backend roles only (no [web] extra needed)

The same entry point is installed as the rtxclaw-serve console script, and python -m rtxclaw is an alias. There is deliberately no service supervisor and no restart loop: a component that dies is reported by name, never respawned.

Inside a source checkout, rtxclaw.bat / rtxclaw-stop.bat / rtxclaw-status.bat wrap these same three commands for Windows.

Core Packages

Modular packages under src/ — installed as pip install rtxclaw:

Extras

• [full] — trafilatura (web-fetch), markitdown (PDF/DOCX), yt-dlp + youtube-transcript-api (YouTube), imageio-ffmpeg (voice-note transcode)
• [web] — Flask for the browser chat frontend (waitress on Windows, gunicorn on POSIX)
• [stt] — faster-whisper (CPU-only STT for Telegram voice)
• [bedrock] — boto3/botocore for the native Amazon Bedrock Converse transport. The tested SDK minimum is 1.43.101; older SDKs fail before client construction. Optional: a non-Bedrock install must never need the AWS SDK.
• [whatsapp] — neonize (Go whatsmeow) linked-device transport for rtxclaw_whatsapp. Needs the system libmagic1 library.

WhatsApp (self-chat channel)

Talk to your agent from WhatsApp: rtxclaw links to your account as a companion device (like WhatsApp Web, shown as "rtxclaw" under Linked devices). You write in your own "Message yourself" chat and the agent answers in the same chat, including turns that finish later in the background.

pip install 'rtxclaw[whatsapp]'           # plus: apt install libmagic1
rtxclaw whatsapp link                     # scan the QR (also saved as ~/.rtxclaw/whatsapp/link-qr.png)
rtxclaw whatsapp link --phone +5511...    # or get an 8-character pairing code instead
rtxclaw whatsapp install-service          # systemd user unit rtxclaw-whatsapp.service
rtxclaw whatsapp status

In the chat, /new starts a fresh session, /stop stops a turn, /agent <name> switches agents and /status shows the link. Every other /command runs in the agent runtime. Voice notes are transcribed through the stt service, and agent questions or permission prompts are answered by replying with a number.

• Privacy. The service only reads and writes your self-chat. Other chats are ignored and never logged.
• Credentials. ~/.rtxclaw/whatsapp/neonize.sqlite3 is a live WhatsApp login, stored with permissions 0600. rtxclaw whatsapp logout revokes it.
• Terms of service. This is an unofficial client, the same approach as WhatsApp Web automation tools. Keep it to your own self-chat. Settings live in ~/.rtxclaw/whatsapp/config.json (design: docs/2026-09-24-whatsapp-channel-design.md).

Amazon Bedrock (native Converse)

rtxclaw talks to Bedrock through the native Converse / ConverseStream API (not the OpenAI-compatible endpoint). Install the optional SDK:

pip install 'rtxclaw[bedrock]'          # release
pip install -e '.[bedrock]'             # editable clone

With AWS credentials already in the service environment, native agents discover Bedrock models automatically; no provider entry or setup wizard is required. Discovery uses AWS_REGION, then AWS_DEFAULT_REGION, then the AWS profile's region, and defaults to sa-east-1 when none is set. Environment IAM keys (including temporary session tokens), Bedrock bearer tokens, explicit AWS profiles, shared credentials, and container/web-identity credentials are supported. It does not probe EC2 instance metadata just to populate the picker.

At model load, rtxclaw lists active streaming text foundation models and inference profiles. Results are cached for five minutes within each process; the model picker's refresh bypasses that cache. Catalogue reads make no inference calls. Removing credentials removes automatic rows on the next config reload. Other engines and the selected default model are unchanged. AWS model access and Converse/tool support still depend on the model and account.

For custom aliases, credentials or context limits, add a model row with api: "bedrock-converse" (the explicit marker that selects the transport) or run rtxclaw configure and choose b. Amazon Bedrock. Example row (illustrative — no credentials):

{
  "alias": "bedrock-primary",
  "api": "bedrock-converse",
  "backend": "bedrock",
  "provider": "bedrock",
  "baseUrl": "bedrock://us-east-1",
  "region": "us-east-1",
  "id": "<operators-supply-a-real-foundation-id-or-inference-profile-arn>",
  "auth": "aws-iam",
  "contextWindow": 200000,
  "maxTokens": 8192
}

• Manual rows take precedence over discovered rows for the same region/model. AWS catalogue responses omit context limits, so automatic rows use a conservative 4,096-token context budget and 1,024-token output limit. Set a manual row to use the model's verified larger limits. Discovery never saves credentials in rows.
• baseUrl is a bedrock://REGION display URL only; the SDK derives the real HTTPS endpoint from region. A bedrock:// URL is never parsed as HTTP.

Authentication

Both modes are supported; there is no silent fallback between them.

• auth: "aws-iam" (recommended): the normal boto3 chain — IAM role, instance/container credentials, shared config or AWS_PROFILE (profile on the row overrides AWS_PROFILE in that child worker only). AWS recommends short-lived role credentials over long-term keys.
• auth: "bedrock-api-key": a Bedrock bearer token, resolved per-agent first (secrets.env / api_keys) then inherited environment, under apiKeyEnv (default AWS_BEARER_TOKEN_BEDROCK). An explicit empty value means "no key" and blocks the environment fallback. The value is set only in the child worker's environment at request time and is never written to config.json, sessions, logs or the request JSON.

Permissions and pricing

• Least privilege: bedrock:InvokeModelWithResponseStream for normal turns, plus bedrock:InvokeModel if a one-shot path (vision transcription, compaction, distillation) is used.
• Automatic discovery also needs bedrock:ListFoundationModels and bedrock:ListInferenceProfiles. A profile-list denial still allows direct foundation models; discovery failure leaves manual rows available.
• Enable model access and any cross-region inference profile in the AWS console for the target account/region.
• Costs come from the metrics the worker reports (provider bedrock) plus the operator's ~/.rtxclaw/pricing.json. Bedrock model/region prices vary; set exact model or alias overrides from the AWS price sheet rather than a blanket rate.

Compatibility and limitations

• Streaming text, client-side tool calls/results and image blocks are supported where the chosen model supports them.
• Extended reasoning is off in v1: no additionalModelRequestFields thinking, the picker//effort marks depth unsupported, and signed reasoningContent during a tool turn fails closed rather than replaying an unsigned assistant turn.
• rtxclaw doctor --health checks a Bedrock route offline (region/auth and credential presence). rtxclaw doctor --bedrock-smoke makes an explicit, opt-in, billable live call; it is never run by --health.

Memory index maintenance

Normal maintenance is automatic: remember indexes immediately after a successful write, memory search lazily indexes detected drift before querying, and the gateway heartbeat asks the persistent memory service to reindex only when needed. The Markdown files remain the source of truth; memory.db is a rebuildable search index.

Use the operator CLI when checking or repairing an agent explicitly:

# Show file/chunk/vector counts, index scope, and whether drift is pending.
rtxclaw memory status --agent codex

# Safe incremental pass: changed files and missing vectors only.
rtxclaw memory index --agent codex

# Rebuild chunks/FTS/vectors, retaining reusable embedding-cache rows.
rtxclaw memory index --agent codex --force

# Also discard the cache and call the configured embedding provider again.
rtxclaw memory index --agent codex --reembed

Start with the incremental command. --force rebuilds only the derived index; it does not delete the Markdown memories. --reembed is the expensive recovery path for a changed model or poisoned cache and requires a working embedding provider.

rtxclaw is the cypherpunk version of inference.

It exists to empower the user to have total control over their data and ideas, without the hassle of endless configuration or requiring deep open-source model knowledge just to get useful work done.

This project starts from a hard truth: the AI industry is underinvesting in infrastructure and degrading model quality to keep up with demand. Decisions like blocking OpenClaw from the Max plan and forcing heavy API costs on users reinforce the view that AI companies are sucking people and companies' ideas like the Matrix uses human crops for creativity and for studying human thought processes.

That is the opposite of sovereignty.

The current model asks users and companies to pour their private context, internal reasoning, product ideas, and operational intelligence into centralized AI systems they do not control. In return, they get rising costs, shrinking access, degraded quality under load, and dependence on infrastructure decisions made by someone else.

And the risk is not theoretical.

The imminent Taiwan conflict will create heavy shocks to current business. Any company relying on AI will have no option but to pay the price of neoclouds if supply chains seize up and centralized inference tightens further. Businesses that chose not to build on-prem infrastructure, or at least retain the option, will be trapped into paying whatever the market demands.

rtxclaw is the answer to that trap.

rtxclaw is a custom-built agent system that adapts to the available inference capacity by creating tailored agents for each hardware profile, from a modest RTX 3060 to RTX 3090, RTX 4090, RTX 5090, A6000-class workstations, and up to advanced rented neocloud GPUs on platforms like Vast.ai.

Instead of forcing every task through one oversized, expensive, centralized stack, rtxclaw rightsizes inference to the real job:

• small agents on cheap local hardware
• stronger agents on workstations
• burst agents on rented neocloud GPUs
• flexible routing based on actual available capacity
• model selection based on task value, latency, and hardware envelope
• agent behavior shaped around the realities of the machine it runs on

Agents can be spawned in seconds using the right-sizing capacity for each task, reducing the cost of AI while increasing resilience, performance, and control.

Why rtxclaw exists

Most AI products are built around a hidden assumption: the user should adapt to the vendor.

The vendor chooses the models.
The vendor chooses the pricing.
The vendor chooses when quality gets degraded.
The vendor chooses which products get blocked.
The vendor chooses which workloads are too expensive.
The vendor chooses whether your use case is welcome.

rtxclaw rejects that model.

The intelligence layer of a company is too important to outsource blindly. Your prompts are not just prompts. They are product direction, customer knowledge, internal process, strategy, failure modes, experimentation, and judgment in raw form. If your AI stack is not sovereign, your cognition stack is not sovereign.

Core Principles

• Own the data: Single-file session logs stored locally on your machine.
• Own the ideas: No outbound telemetry leaks.
• Own the inference path: Seamless fallback between local vLLM, private workstations, and cloud models.
• Instant Responsiveness: < 5ms submission ACKs on all inputs, < 2ms UI cache reads from SQLite.
• Zero Configuration Sprawl: Single .jsonl session files, extensible JSON tool containers, zero sidecars.
• Clean Protocol Boundaries: ACP for IDE control (North-South), A2A for multi-agent swarms (East-West).
• Cancel Scopes You Can Reason About: Abort one turn and only that turn dies; abort a subagent and only that subagent terminates.

Architecture Overview

The canonical system architecture is documented in detail in the Technical Specifications.

Runtime: rtxclaw gateway start brings up the south orchestrator (:8099) then the north gateway (:8100). rtxclaw gateway stop stops both.

flowchart TD
    Clients["Multi-Interface Clients<br/><b>WebUI • Telegram • TUI • IDE (via ACP)</b>"]
    
    Gateway["rtxclaw_gateway (North)<br/>• Ingress Auth & Multi-Source Queue (<5ms ACK)<br/>• Fast SQLite Cache Server (<2ms)<br/>• Multi-Subscriber SSE Streamer"]
    
    Orchestrator["rtxclaw_orchestrator (South)<br/>• Turn & Round State Machine<br/>• Multi-Modal Engine Adapters (CLI, ACP, A2A)<br/>• Tool Dispatch & AI Model Telemetry"]
    
    Storage["rtxclaw_session (Storage Engine)<br/>• Single-File Ledger (<session_id>.jsonl)<br/>• Instant SQLite Cache (sessions.db)"]
    
    Clients -->|"1. Submit Prompts & Subscribe Stream"| Gateway
    Gateway -->|"2. Priority Ingress Queue (FIFO)"| Orchestrator
    Orchestrator -->|"3. Append Events, Row Markers, & Project Cache"| Storage
    Gateway -.->|"4. Fast REST Reads & SSE Tails"| Storage

1. Storage Tier (rtxclaw_session)

• Single-File Ledger (<session_id>.jsonl): Exactly 1 immutable, append-only file per session. Zero loose sidecars.
• Materialized SQLite Cache (sessions.db): Atomic single-row reads for instant UI loading (< 2ms).
• Extensible JSON Containers (tools_state_json): Dynamic tool state updates (Kanban, Todos, Canvas) via json_set() with zero database schema migrations.
• Row Range Markers: Exact [start_row_idx, end_row_idx] recorded for every turn and every AI model call.

2. Multi-Modal Execution (rtxclaw_orchestrator)

• CLI Adapter: Invokes subprocess CLI tools (agy, claude, codex) and wraps them into standard message envelopes.
• ACP Adapter: Interacts with external IDEs (Cursor, Zed) via JSON-RPC 2.0.
• A2A Adapter: Coordinates autonomous subagents via native a2a/v1 message envelopes.
• AI Telemetry Collector: Captures TTFT, generation speed (tokens/sec), routing overhead, token volume, and cost ($) into the ai_generations table.

3. Edge Membrane (rtxclaw_gateway)

• Session Ingress Queue: Immediate < 5ms submission ACK for WebUI, Telegram, TUI, A2A subagents, and schedulers.
• Priority Intake: Priority 0 (Control) $\rightarrow$ Priority 1 (Subagent Returns) $\rightarrow$ Priority 2 (User Prompts) $\rightarrow$ Priority 3 (System Nudges).
• Row-Indexed SSE Streaming: Clients seek directly to any row (GET /stream?from=<row_idx>) with zero token loss and zero duplicate frames.

Documentation Roadmap

The full system documentation is organized into 10 domain directories matching the WebUI tabs:

• Requirements (WHAT): Product specifications, functional requirements (FR-01 to FR-11), and quality SLAs.
• Technical Specifications (HOW): Authoritative architecture contracts, Mermaid diagrams, event wire schemas, and SQLite table definitions.
• Implementation Plans (WHEN): Phase-by-phase engineering execution roadmaps and automated test verification suites.