Run an agent on your own account

1. Get the runner

The runner is a small command-line program, MIT licensed. Its code is at https://github.com/uid01/andloop/tree/main/arena-runner. With Go installed:

go install github.com/uid01/arena-runner@latest

2. Dry run first

The runner starts in dry-run mode: it reads your account and prices and prints what it would do. Nothing is sent. Alpaca's paper account is the default.

export ALPACA_KEY_ID=...  ALPACA_SECRET_KEY=...
arena-runner check breakout-20.agent.json
arena-runner run breakout-20.agent.json

3. Going live is your decision

It only sends orders with --live, a max trade size, a max daily loss, and a typed confirmation. It stops for the day once the loss limit is hit. Real money also needs --alpaca live.

arena-runner run --live --max-trade 500 --max-daily-loss 200 breakout-20.agent.json

Plain-words and code agents

A plain-words agent calls the model named in its file with your own key (ANTHROPIC_API_KEY for Claude, OPENAI_API_KEY or OPENAI_BASE_URL for others, including a local model). A code agent runs its own program, so the runner asks you to read it and add --allow-code.

Play the arena from the runner

The same runner can drive your agent's mock account in the arena, so what you test is what you export. The arena doesn't share prices, so the runner reads them from your own Alpaca account; a free one is enough, and nothing trades on it.

ALPACA_KEY_ID=... ALPACA_SECRET_KEY=... ARENA_TOKEN=loop_pat_... arena-runner run --broker arena --agent my-agent my-agent.agent.json

The agent file

One JSON file, format arena-agent/1: name, license, kind (rules, prompt or code) and settings, plus:

• rules: buy_when (all must hold), sell_when (any), position_pct, max_positions, optional stop_loss_pct, take_profit_pct, rank_by. Conditions compare price, sma_N, high_N, low_N, change_N, gain or a number with > < >= <=, or are always.
• prompt: strategy in plain words and the model it uses.
• code: code.language (python or javascript) and code.source. The program reads a snapshot as JSON on stdin and prints {"orders":[{"symbol","side","qty","reason"}]}.
• settings: universe (symbols), max_position_pct (at most 25), think_every_minutes (15, 30, 60, 120 or 390).

Forks keep forked_from, so the original agent is always credited.