Quickstart & Multi-Platform Setup

100% CROSS-PLATFORM COMPATIBLE

OpenCatz AI is built with Node.js and TypeScript, designed to run natively and seamlessly across Windows (PowerShell, Command Prompt / CMD, Windows Terminal), Linux (Ubuntu, Debian, CentOS, Arch, VPS), macOS, and containerized Docker environments.

System Prerequisites

Node.js: ≥ 22.12 (LTS recommended) — verify with node -v
Package Manager: npm (≥ 10.x) or pnpm
Version Control: git
Target Network: Robinhood Chain L2 (EVM Chain ID 4663, Native Token: ETH)
Required Credentials: Discord Bot Token & Client ID (for Discord Command Center)
Optional APIs: OpenRouter/Anthropic/OpenAI/Gemini (AI Intelligence), GMGN (DEX data), Krystal Cloud (LP pools), OpenSea (NFTs), X API v2 (Social sentiment), Telegram Bot Token (Push bridge)

Interactive Platform Quick Switcher

Choose your operating system and environment to view tailored setup steps:

🪟 Windows PowerShell Setup

Open Windows PowerShell or Windows Terminal and execute:

1. One-Click Setup (Recommended)

# Clone the official repository
git clone https://github.com/dizcorvus/opencatz-ai.git
cd "opencatz-ai"

# Run the automated Windows installer batch script
.\setup.bat

2. Manual Step-by-Step in PowerShell

# Step A: Install dependencies & compile TypeScript
npm install
npm run build

# Step B: Launch interactive onboarding wizard (.env configuration)
npm run wizard

# Step C: Start live bot in development mode
npm run dev

# Step D: (Optional) Open standalone 24-bit TrueColor Terminal TUI
npm run terminal

3. Running 24/7 in Background on Windows

# Start background daemon via PM2
npx pm2 start dist/index.js --name opencatz-agent --update-env

# View process status & live screening logs
npx pm2 status
npx pm2 logs opencatz-agent

💡 PowerShell Execution Policy Tip: If PowerShell blocks scripts, run: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass in your session.

💻 Windows Command Prompt (CMD) Setup

Open cmd.exe (Command Prompt) and run:

1. One-Click Batch Setup

:: Clone the repository
git clone https://github.com/dizcorvus/opencatz-ai-robinhood-chain.git
cd opencatz-ai-robinhood-chain

:: Execute setup batch script
setup.bat

2. Manual Setup & Command Execution in CMD

:: Install dependencies
npm install

:: Build TypeScript code to /dist
npm run build

:: Launch guided interactive setup wizard
npm run wizard

:: Launch live screening bot
npm run dev

:: Launch standalone Command Center Terminal TUI
npm run terminal

3. Direct Node.js Binary Invocation in CMD

:: Run any command without global links:
node bin\opencatz.js onboard
node bin\opencatz.js run
node bin\opencatz.js terminal
node bin\opencatz.js doctor

🐧 Linux / macOS / VPS Setup

Tested on Ubuntu 22.04/24.04 LTS, Debian 12, CentOS/RHEL 9, Arch Linux, and macOS (Intel & Apple Silicon):

Option A: Automatic One-Liner (curl)

# Download installer, clone repository, compile, and link CLI
curl -fsSL https://opencatz.xyz/install.sh | bash

# Launch guided onboarding wizard
opencatz onboard

# Deploy 24/7 background daemon
opencatz deploy

Option B: Manual Git Source Setup

# Clone and run shell bootstrap script
git clone https://github.com/dizcorvus/opencatz-ai-robinhood-chain.git
cd opencatz-ai-robinhood-chain
bash setup.sh

# Complete configuration wizard
opencatz onboard

# Start live bot
opencatz run

24/7 Daemon & Automatic Self-Updater

# Start/reload background daemon via PM2
opencatz deploy

# Self-update engine (git stash -> pull -> install -> build -> PM2 restart)
opencatz update

# System diagnostics & health check
opencatz doctor

📦 Standard Node.js & npm Workflow

Universal commands that work identically across every OS without requiring global CLI symlinks:

# 1. Clone repository
git clone https://github.com/dizcorvus/opencatz-ai-robinhood-chain.git
cd opencatz-ai-robinhood-chain

# 2. Install dependencies & compile
npm install
npm run build

# 3. Interactive onboarding configuration
npm run wizard

# 4. Start live agent bot
npm run dev

# 5. Start standalone interactive Terminal TUI
npm run terminal

# 6. Run full unit test suite (264+ tests)
npm run test

# 7. Run system diagnostic check
npm run doctor

# 8. Deploy / update 24/7 PM2 daemon
npm run deploy
npm run update

🐳 Docker Containerized Setup

Run OpenCatz in an isolated, lightweight container with persistent state volume:

# 1. Create your local .env configuration from example
cp .env.example .env

# 2. Run container with automatic restart
docker run -d \
  --name opencatz-agent \
  --restart always \
  --env-file .env \
  -v $(pwd)/database:/app/database \
  -p 3000:3000 \
  ghcr.io/dizcorvus/opencatz-ai:latest

# 3. View container logs
docker logs -f opencatz-agent

Guided Interactive Onboarding Wizard (`opencatz onboard`)

When you run opencatz onboard (or npm run wizard), OpenCatz launches a clean, interactive terminal wizard that configures your environment in 7 structured steps:

STEP 1 Network & RPC Endpoints

Configures canonical Robinhood Chain L2 RPC (https://rpc.mainnet.chain.robinhood.com) and sets up automatic failover RPC endpoints.

STEP 2 AI Provider & Model Pool

Select your LLM intelligence provider: OpenRouter (recommended, free models available), Anthropic Claude, OpenAI, Google Gemini, DeepSeek, or MiniMax with automatic backup key rotation.

STEP 3 Market Intelligence & Security Keys

Input API keys for 24/7 screening daemons: GMGN (DEX data & rank), Krystal Cloud (Uniswap V3 LP pools), OpenSea (NFT floor), X API v2 (Social sentiment), and GoPlus (EVM honeypot security).

STEP 4 Burner Wallet & Safety Mode

Generate or import a dedicated trading burner wallet. OpenCatz defaults to DRY_RUN=true (safe simulation mode with zero risk to funds) until live execution is explicitly enabled.

STEP 5 Screening Strategy & Strictness

Choose screening preset: Loosened Default (2x signals), Standard (Strict), Custom Natural Language Prompt (compiled to .mjs automatically), or Numeric Matrix.

STEP 6 9-Lives Risk Engine & TP/SL

Set automated Take-Profit (TP1 +100% / 2x, TP2 +200% / 3x), Stop-Loss (-20% hard floor), and dynamic trailing stop-loss milestones.

STEP 7 Discord & Telegram Command Center

Link your Discord bot token and optional Telegram push bridge. On first launch, OpenCatz automatically provisions all channels and registers 22 slash commands.

Cross-Platform CLI Invocation Matrix

Depending on whether you use global installation, npm scripts, or direct Node.js binaries, all commands map seamlessly:

Task	Global CLI (`opencatz`)	npm script	Direct Node Binary
Interactive Setup Wizard	`opencatz onboard`	`npm run wizard`	`node bin/opencatz.js onboard`
Start Live Bot	`opencatz run`	`npm run dev`	`node bin/opencatz.js run`
Interactive Terminal TUI	`opencatz terminal`	`npm run terminal`	`node bin/opencatz.js terminal`
Deploy 24/7 PM2 Daemon	`opencatz deploy`	`npm run deploy`	`node bin/opencatz.js deploy`
Auto-Update Code & Daemon	`opencatz update`	`npm run update`	`node bin/opencatz.js update`
System Diagnostics (Doctor)	`opencatz doctor`	`npm run doctor`	`node bin/opencatz.js doctor`
Run Vitest Test Suite	`opencatz test`	`npm run test`	`npm test`
Clean Uninstall / Reset	`opencatz uninstall`	`npm run uninstall`	`node bin/opencatz.js uninstall`

Automated Discord Server Bootstrap

When OpenCatz boots with a valid DISCORD_BOT_TOKEN, it connects to your server and automatically creates the dedicated category and 7 channels — no manual channel setup required:

Channel	Role & Description
`#opencatz-control-room`	Core command hub — natural language AI chat, burner wallet controls, risk switches, and portfolio overview.
`#audit-on-demand`	Paste any Robinhood Chain / EVM Contract Address for an instant 12-point GoPlus & GMGN security honeypot audit.
`#call-meme-robinhood`	Vetted meme token breakout signal cards (GMGN smart-money + GoPlus security audit + ≥$25k vol).
`#call-lp-robinhood`	Uniswap V3 concentrated liquidity velocity alerts (Krystal Cloud data, TVL ≥$10k, Fee/TVL ≥2%).
`#call-nft-robinhood`	OpenSea secondary floor sweeps and rare trait sniping alerts (Floor surge ≥+10%/1h, sales ≥3/h).
`#call-alpha-robinhood`	1-Hour Robinhood Chain alpha scraper & official X (Twitter) API v2 social sentiment catalyst calls.
`#call-whale-eth`	Hyperliquid L1 institutional ETH derivatives positioning & spot flow tracking (perps ≥$500k, spot ≥$50k).

Verifying System Health (`opencatz doctor`)

Run diagnostics anytime to verify your RPC latency, API key rate limits, database status, and Discord connection:

# Run diagnostic verification:
opencatz doctor
# (or: npm run doctor)

Frequently Asked Questions & Troubleshooting

Is `DRY_RUN` safe for beginners?

Yes! OpenCatz operates with DRY_RUN=true by default. In this mode, no real on-chain transactions are signed. All swap signals, profit targets, and stop losses are safely simulated in memory.

Can I run OpenCatz without Discord?

Absolutely. You can run the full standalone Interactive Terminal TUI (opencatz terminal or npm run terminal) or connect your own frontend / dashboard via the built-in Web REST API on port 3000.

How do API key failovers work?

If any API endpoint hits a rate limit (HTTP 429) or temporary error, OpenCatz automatically rotates to your backup keys defined in _BACKUP_KEYS in your .env without dropping the screening cycle.