Getting Started

Deploy the Worker, connect Sentinel, and start with paper trading.

Prerequisites

Node.js 18 or higher
Alpaca account (free, supports paper trading)
LLM API key or Cloudflare AI Gateway credentials
Optional: Alpha Vantage API key, Reddit cookies, Twitter/X cookies

Recommended Path: Sentinel

For normal operation, use MAHORAGA-Next SENTINEL. Deploy the Worker, install Sentinel from GitHub Releases, then enter your Worker URL and MAHORAGA_API_TOKEN. Sentinel can edit runtime config, test Reddit/Twitter/X cookie accounts, set Alpha Vantage, download trade-review logs, and install future app updates.

1. Clone and Install

git clone https://github.com/MAV3Ndev/MAHORAGA-Next.git
cd MAHORAGA-Next
npm install
cd dashboard && npm install && cd ..

2. Configure API Keys

For production, use wrangler secret put. For local development, the same names can be stored in .dev.vars.

npx wrangler secret put ALPACA_API_KEY
npx wrangler secret put ALPACA_API_SECRET
npx wrangler secret put ALPACA_PAPER
npx wrangler secret put MAHORAGA_API_TOKEN
npx wrangler secret put KILL_SWITCH_SECRET
npx wrangler secret put LLM_PROVIDER
npx wrangler secret put LLM_MODEL
npx wrangler secret put OPENAI_API_KEY

Generate secure tokens with: openssl rand -base64 48

Important: Always start with ALPACA_PAPER=true until you understand how the system works.

Secret	Purpose
`MAHORAGA_API_TOKEN`	Required for all API access (dashboard, curl commands)
`KILL_SWITCH_SECRET`	Emergency shutdown + approval token signing
`ALPHA_VANTAGE_API_KEY`	Optional news sentiment source; can also be set in Sentinel config
`REDDIT_COOKIES`	Optional fallback; Sentinel supports multiple rotated accounts
`TWITTER_COOKIES`	Optional fallback; Sentinel supports multiple rotated accounts

3. Get Your API Keys

Alpaca (Required)

Create a free account at alpaca.markets
Go to Paper Trading → API Keys
Click Generate New Keys
Copy both the key and secret to .dev.vars

OpenAI (Required)

Create an account at platform.openai.com
Add billing and credits ($10 is plenty to start)
Go to API Keys → Create new secret key
Add to .dev.vars: OPENAI_API_KEY=sk-your_key

Estimated costs: ~$0.50-2/day using gpt-4o-mini, depending on trading activity.

4. Start the Server

npm run dev

The server runs at http://localhost:8787. You should see output like:

Ready on http://localhost:8787

5. Enable the Trading Agent

All API endpoints require your MAHORAGA_API_TOKEN:

# Set your token (copy from .dev.vars)
export MAHORAGA_TOKEN="your_token_here"

# Enable the agent
curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  http://localhost:8787/agent/enable

# Check status
curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  http://localhost:8787/agent/status

The agent will start monitoring configured signal sources. By default this includes StockTwits, Reddit, SEC, GDELT, Alpha Vantage when configured, and crypto momentum.

6. Open the Dashboard (Optional)

In another terminal:

cd dashboard
npm run dev

Open http://localhost:5173 in your browser.

First time setup: Click the Settings icon and enter your MAHORAGA_API_TOKEN to authenticate.

The dashboard/Sentinel shows:

Account balance and positions
Current signals and research
Agent activity logs
Runtime config and credential connection tests
Trade-review log export with optional R2 snapshots

What Happens Next

The agent runs in a loop:

Data gathering (24/7) — Fetches social, news, filing, and crypto signals
LLM research — Analyzes top candidates for red flags and catalysts
Trading (market hours) — Executes buy/sell based on LLM decisions
Position management — Monitors held positions for exit signals

Next Steps

Configuration — Customize trading parameters
Sentinel — Desktop and Android app operations
Architecture — How the system works
Extending — Add your own data sources