Guides

Live deployments

Run a local Alpaca paper or live strategy and stream telemetry into AlphaLens Strategy Center.

AlphaLens Core docs

Quickstart Build a strategy How AlphaLens hosting works Sync backtests Live deployments Python API CLI reference Environment setup Troubleshooting

Live deployments use the same Algorithm class as backtests. The local runner subscribes to completed bars, updates strategy state, sends orders to Alpaca, and streams telemetry to AlphaLens.

Prerequisites

Install the live and cloud extras:

bash

pip install "alphalens-core[live,cloud,fast]"

Set local environment variables:

bash

ALPHALENS_API_KEY=alens_...
ALPACA_API_KEY=...
ALPACA_SECRET_KEY=...
ALPACA_PAPER=true

ALPACA_PAPER=true is optional for CLI paper runs because paper is the default. Keep it explicit in .env.local so the local environment is obvious.

Start paper trading

bash

alphalens live --strategy my_strategy:MyStrategy

By default, the live runner uses:

Setting	Default
Broker	Alpaca
Account mode	Paper
Market data	AlphaLens-hosted data endpoints
Telemetry	Enabled
State checkpoint	`.alphalens/live/<strategy>.json`

Name and reuse deployments

Give a deployment a readable name:

bash

alphalens live \
  --strategy my_strategy:MyStrategy \
  --deployment-name "MomentumRotation paper"

Reuse a deployment record across restarts:

bash

alphalens live \
  --strategy my_strategy:MyStrategy \
  --deployment-id 00000000-0000-0000-0000-000000000000

Reusing the deployment ID keeps the Strategy Center monitor continuous.

Route live orders

Only use --live after the paper deployment behaves correctly:

bash

alphalens live --strategy my_strategy:MyStrategy --live

Startup sequence

On startup, the local runner:

Loads the strategy class.
Reads universe, resolution, warmup, and constructor parameters.
Connects to Alpaca.
Loads broker cash, positions, and open orders.
Fetches historical bars for warmup.
Calls initialize and on_warmup_finished.
Starts polling for completed live bars.
Calls schedules and on_data as bars arrive.
Emits telemetry to AlphaLens.

If a strategy schedules hourly execution on 5-minute bars, the runner may log bar progress before orders are expected. That is normal.

Telemetry

Live deployments can emit:

Telemetry	Used for
Heartbeat and status	Stale deployment detection
Account snapshots	Live equity and cash
Position snapshots	Holdings and allocation
Latest processed bar	Live data health
Target weights	Signal inspection
Signal explanations	Debugging strategy decisions
Orders and fills	Execution audit trail
Structured logs	Operational monitoring

Telemetry writes are best-effort. AlphaLens cloud failures should log a warning but should not stop trading.

Useful flags

bash

alphalens live \
  --strategy my_strategy:MyStrategy \
  --history-bars 50000 \
  --poll-sec 20 \
  --idle-log-sec 60 \
  --state-path .alphalens/live/momentum-paper.json

Flag	Purpose
`--history-bars`	Number of bars seeded before live processing
`--history-max-bars`	Maximum retained rolling bars
`--state-path`	Checkpoint path
`--poll-sec`	Poll interval while waiting for bars
`--idle-log-sec`	Cadence for idle waiting logs
`--allow-open-orders`	Start even if Alpaca reports open orders
`--continue-on-error`	Continue polling after strategy callback errors
`--no-telemetry`	Run locally without AlphaLens telemetry writes

Strategy Center monitor

Open Dashboard -> Strategy Center and select the deployment source. A healthy paper or live deployment should show:

Recent heartbeat.
Latest processed bar time.
Current equity and cash.
Current positions.
Target and current weights.
Orders and fills.
Logs or warnings if data or telemetry is stale.

Sync backtests

Python API