### Setup virtual environment and install package

Source: https://github.com/enarjord/passivbot/blob/master/docs/ai/runbooks/commands.md

Creates a virtual environment, activates it, and installs the package in editable mode. The default install is live-only; use the commented alternatives for full or dev extras.

```bash
python3 -m venv venv
source venv/bin/activate
python3 -m pip install -e .              # live-only
# or: python3 -m pip install -e ".[full]"
# or: python3 -m pip install -e ".[dev]"
```

--------------------------------

### Run fake live with sample config and scenario

Source: https://github.com/enarjord/passivbot/blob/master/docs/fake_live.md

Quick start example using the included sample config and scenario. Writes artifacts under artifacts/fake_live/ by default.

```shell
PYTHONPATH=src python3 src/tools/run_fake_live.py \
  configs/examples/fake_live_hsl.json \
  scenarios/fake_live/hsl_long_red_restart.hjson \
  --user fake_hsl_restart_test \
  --snapshot-each-step
```

--------------------------------

### Run the fill events dashboard with basic and advanced options

Source: https://github.com/enarjord/passivbot/blob/master/docs/fill_events_session_summary.md

Basic usage starts the dashboard with a comma-separated list of users. The advanced example adds a config file, lookback days, port, and log level.

```bash
# Basic usage
python3 src/tools/fill_events_dash.py --users binance_01,bybit_01,gateio_01
```

```bash
# With options
python3 src/tools/fill_events_dash.py \
  --users binance_01,bybit_01 \
  --config configs/examples/default_trailing_martingale_long.json \
  --lookback-days 60 \
  --port 8050 \
  --log-level info
```

--------------------------------

### Setup: Load autoreload and run notebook_setup.py

Source: https://github.com/enarjord/passivbot/blob/master/notebooks/notes_backtest.ipynb

Initializes the notebook environment by enabling autoreload and running the setup script.

```python
%load_ext autoreload
%autoreload 2
%run notebook_setup.py
```

--------------------------------

### Optimize with a starting config pool

Source: https://github.com/enarjord/passivbot/blob/master/docs/optimizing.md

Example invocation that uses an existing config as a starting point. The canonical default profile keeps backtest.suite_enabled = false, so optimize runs are single-scenario by default unless suite mode is explicitly enabled.

```bash
passivbot optimize configs/examples/default_trailing_martingale_long.json --start configs/starting_pool/
```

--------------------------------

### Set up and run passivbot with a private config

Source: https://github.com/enarjord/passivbot/blob/master/docs/config_workflow.md

Sets up a private config from the example file, then runs backtest, optimize, and live commands. Use after editing the config for your account and strategy. The backtest and optimize commands use the -s BTC and -sd 2025 flags; optimize also uses -c 4. The live command starts a live run that writes a timestamped log under logs/ by default.

```bash
mkdir -p configs/private
cp configs/examples/default_trailing_martingale_long.json configs/private/my_config.json
passivbot backtest configs/private/my_config.json -s BTC -sd 2025 --suite n
passivbot optimize configs/private/my_config.json -s BTC -sd 2025 -c 4 --suite n
passivbot live configs/private/my_config.json
```

--------------------------------

### Install full profile for optimization

Source: https://github.com/enarjord/passivbot/blob/master/docs/optimizing.md

Install the full profile required for optimization. Use this command in the project root to install the package with all dependencies needed for running the optimizer.

```bash
pip install -e ".[full]"
```

--------------------------------

### Install and launch JupyterLab

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Install and launch JupyterLab from the repository root after activating the bot virtual environment.

```shell
python3 -m pip install jupyterlab
python3 -m jupyter lab
```

--------------------------------

### docker-compose.yml: Reference example for live deployment

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/container_deployment_design.md

Recommended docker-compose.yml example for a live PassivBot deployment, mounting configs, API keys, logs, and monitor directories, and setting the user via environment variable.

```yaml
services:
  passivbot-live:
    build:
      context: .
      dockerfile: Dockerfile_live
    environment:
      PB_USER: bitget_01
      PB_CONFIG_PATH: /data/configs/live.json
      PB_API_KEYS_PATH: /data/api-keys.json
    volumes:
      - ./configs:/data/configs:ro
      - ./api-keys.json:/data/api-keys.json:ro
      - ./logs:/data/logs
      - ./monitor:/data/monitor
```

--------------------------------

### Install Passivbot with pip

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Installation commands for different use cases: live trading only, full install for backtesting/optimization/downloader/advanced tools, and dev install for contributor tooling.

```shell
python3 -m pip install -e .
```

```shell
python3 -m pip install -e ".[full]"
```

```shell
python3 -m pip install -e ".[dev]"
```

--------------------------------

### Install GPU backend for Apple Silicon

Source: https://github.com/enarjord/passivbot/blob/master/docs/optimizing.md

Installs the GPU backend for Apple Silicon. Requires the normal optimizer dependencies plus the GPU runtime for the platform.

```bash
python3 -m pip install -e ".[full,gpu-mps]"
```

--------------------------------

### Copy custom endpoints example config

Source: https://github.com/enarjord/passivbot/blob/master/docs/live.md

Copy the example custom endpoints configuration file to the active config file.

```sh
cp configs/custom_endpoints.json.example configs/custom_endpoints.json
```

--------------------------------

### Startup log entries for custom endpoints

Source: https://github.com/enarjord/passivbot/blob/master/docs/live.md

Example log output showing custom endpoint overrides being applied at startup.

```text
INFO Custom endpoint active for binanceusdm.fapiPrivate: https://fapi.binance.com/fapi/v1 -> https://proxy.example.exchange/fapi/v1
INFO Custom endpoint override active for binanceusdm (disable_ws=True, source=...)
```

--------------------------------

### Install and verify GPU backend for NVIDIA

Source: https://github.com/enarjord/passivbot/blob/master/docs/optimizing.md

Installs the GPU backend for NVIDIA on Linux or WSL2 (Python 3.12 recommended) and verifies CUDA availability. Requires a compatible NVIDIA driver; in WSL2 install the driver on Windows, not inside Ubuntu. No system-wide CUDA toolkit is required.

```bash
python3 -m pip install -e ".[full,gpu-cuda]"
```

```bash
python3 -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name())"
```

--------------------------------

### Install full profile for backtesting

Source: https://github.com/enarjord/passivbot/blob/master/docs/backtesting.md

Install the full Passivbot profile, which is required for backtesting. Use this before running any backtest or optimizer preparation.

```shell
python3 -m pip install -e ".[full]"
```

--------------------------------

### Run Passivbot live with config file

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Starts the bot with a custom configuration file. Use configs/examples/default_trailing_martingale_long.json as a starting point for new configs.

```sh
passivbot live path/to/config.json
```

--------------------------------

### Start bot with custom endpoints CLI options

Source: https://github.com/enarjord/passivbot/blob/master/docs/live.md

Commands to start Passivbot live with a specific custom endpoints file or disable overrides entirely.

```sh
# Use custom endpoints from a specific file
passivbot live --custom-endpoints configs/custom_endpoints.json configs/your_config.hjson

# Disable overrides even if the file exists
passivbot live --custom-endpoints none configs/your_config.hjson
```

--------------------------------

### Run optimization with passivbot optimize

Source: https://github.com/enarjord/passivbot/blob/master/docs/ai/runbooks/commands.md

Runs optimization with a config, the suite, or with fine-tune anchors. When -ft/--fine-tune-params and -t/--start are used together, start configs are fine-tune anchors; runtime policy from the base config still wins, and seed/anchor values outside optimize.bounds are clamped with aggregated logging.

```bash
passivbot optimize path/to/config.json
passivbot optimize --suite
passivbot optimize path/to/config.json -t path/to/anchor_configs -ft long.forager,long.risk
```

--------------------------------

### Start the web dashboard with passivbot tool monitor-web

Source: https://github.com/enarjord/passivbot/blob/master/docs/monitor.md

Launches the browser monitor dashboard that consumes the aggregate /snapshot + /ws relay feed.

```bash
passivbot tool monitor-web
```

--------------------------------

### Run backtest with ema_anchor.json and date range

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/backtester_performance_optimization_plan.md

Secondary performance command for the new strategy seam. Runs a backtest with the ema_anchor.json example config and specifies start and end dates.

```bash
VIRTUAL_ENV=/Users/eiriknarjord/repos/passivbot-4/venv \
PATH=/Users/eiriknarjord/repos/passivbot-4/venv/bin:$PATH \
passivbot backtest configs/examples/ema_anchor.json -sd 2022-01-01 -ed 2026-04-02
```

--------------------------------

### Copy default v8 trailing martingale config

Source: https://github.com/enarjord/passivbot/blob/master/docs/release_notes_v8.0.0.md

Copies the canonical v8 example config for the trailing_martingale strategy to a new file for a fresh v8 deployment. Use this as a starting point for new configs.

```bash
cp configs/examples/default_trailing_martingale_long.json my_v8_config.json
```

--------------------------------

### Live-only install

Source: https://github.com/enarjord/passivbot/blob/master/docs/installation.md

Typical live-only install. Upgrades pip and installs Passivbot in editable mode, which also builds the Rust extension.

```bash
python3 -m pip install -U pip
python3 -m pip install -e .
```

--------------------------------

### Run live bot (explicit approval required)

Source: https://github.com/enarjord/passivbot/blob/master/docs/ai/runbooks/commands.md

Starts the live bot with an account name or a config file and optional log level. Requires explicit approval under AGENTS.md; may load private keys, configure an account, and create or cancel orders.

```bash
passivbot live -u {account_name}
passivbot live path/to/config.json --log-level {warning|info|debug|trace|0-3}
```

--------------------------------

### Live trading with explicit config

Source: https://github.com/enarjord/passivbot/blob/master/docs/config_workflow.md

Starts live trading using an explicit configuration file. The command passes the path to the config file as an argument.

```bash
passivbot live configs/private/my_config.json
```

--------------------------------

### Update Rust and retry full install

Source: https://github.com/enarjord/passivbot/blob/master/docs/troubleshooting.md

Update to the current stable Rust toolchain and retry the full install.

```bash
rustup update stable
python3 -m pip install -e ".[full]"
```

--------------------------------

### Run fake live harness

Source: https://github.com/enarjord/passivbot/blob/master/docs/fake_live.md

Entry point for the fake live harness. Requires a config file and a scenario file as positional arguments.

```shell
python3 src/tools/run_fake_live.py <config> <scenario>
```

--------------------------------

### Refresh Passivbot install after new commits

Source: https://github.com/enarjord/passivbot/blob/master/docs/troubleshooting.md

Refresh the install after pulling new commits; choose the appropriate extra profile.

```bash
python3 -m pip install -e .
# or: python3 -m pip install -e ".[full]"
# or: python3 -m pip install -e ".[dev]"
```

--------------------------------

### Install Passivbot live-only profile

Source: https://github.com/enarjord/passivbot/blob/master/README.md

Installs Passivbot with the live-only profile. Builds the Rust extension and registers the passivbot command.

```sh
python3 -m pip install -e .
```

--------------------------------

### Run monitor-dev wrapper

Source: https://github.com/enarjord/passivbot/blob/master/docs/monitor.md

Launches the monitor development wrapper for local iteration. It reuses an existing relay if healthy, otherwise starts one automatically, and selects the newest log file unless --log-file is provided.

```bash
passivbot tool monitor-dev --exchange bitget --user bitget_01
```

--------------------------------

### Verify backtest and optimize subcommands

Source: https://github.com/enarjord/passivbot/blob/master/docs/installation.md

Verifies backtesting and optimization environments by displaying help for the backtest and optimize subcommands.

```bash
passivbot backtest -h
passivbot optimize -h
```

--------------------------------

### Docker run with mounted config and API keys

Source: https://github.com/enarjord/passivbot/blob/master/docs/container_deployment.md

Runs the live container using a mounted config file and mounted api-keys.json. Sets PB_CONFIG_PATH, PB_API_KEYS_PATH, PB_LOG_DIR, and PB_MONITOR_ROOT, and mounts the corresponding directories as volumes.

```bash
docker run --rm \
  -e PB_USER=bitget_01 \
  -e PB_CONFIG_PATH=/data/configs/live.json \
  -e PB_API_KEYS_PATH=/data/api-keys.json \
  -e PB_LOG_DIR=/data/logs \
  -e PB_MONITOR_ROOT=/data/monitor \
  -v "$(pwd)/configs:/data/configs:ro" \
  -v "$(pwd)/api-keys.json:/data/api-keys.json:ro" \
  -v "$(pwd)/logs:/data/logs" \
  -v "$(pwd)/monitor:/data/monitor" \
  passivbot-live:latest
```

--------------------------------

### Example initial-focus URL for the dashboard

Source: https://github.com/enarjord/passivbot/blob/master/docs/monitor.md

URL with optional exchange, user, and symbol query parameters for initial focus only; the dashboard still consumes the multiplexed relay feed.

```text
http://127.0.0.1:8765/dashboard?exchange=bitget&user=bitget_01&symbol=BTC/USDT:USDT
```

--------------------------------

### Pareto single-candidate explorer examples

Source: https://github.com/enarjord/passivbot/blob/master/docs/tools.md

Shows various invocations of `passivbot tool pareto` for selecting a candidate from a Pareto front, including default behavior, filtering, saving, and scenario-based analysis.

```shell
passivbot tool pareto optimize_results/.../pareto
```

```shell
passivbot tool pareto
```

```shell
passivbot tool pareto optimize_results/.../pareto -m reference \
  --target adg_strategy_eq=0.001 \
  --target drawdown_worst_strategy_eq=0.25
```

```shell
passivbot tool pareto optimize_results/.../pareto \
  -l 'drawdown_worst_strategy_eq<=0.35' \
  -l 'adg_strategy_eq>0.0' \
  --save-selected configs/promoted_candidate.local.json
```

```shell
passivbot tool pareto optimize_results/.../pareto \
  -l 'drawdown_worst_strategy_eq<=0.35' \
  -l 'adg_strategy_eq>0.0' \
  --save-filtered optimize_results/filtered_pareto
```

```shell
passivbot tool pareto -o sharpe_ratio_strategy_eq,adg_strategy_eq,strategy_eq_recovery_days_max \
  -m ideal
```

```shell
passivbot tool pareto optimize_results/... -m utility \
  --weight adg_strategy_eq=4 \
  --weight drawdown_worst_strategy_eq=2 \
  --show-top 5
```

```shell
passivbot tool pareto optimize_results/... --scenario opt_2025_to_present
```

```shell
passivbot tool pareto --json
```

--------------------------------

### Reinstall passivbot after upgrade

Source: https://github.com/enarjord/passivbot/blob/master/docs/release_notes_v7.10.0.md

Reinstall the package after upgrading to v7.10.0. The first command installs the base package; the second installs the full extras. Use one of these commands in your active environment.

```bash
python3 -m pip install -e .
```

```bash
python3 -m pip install -e ".[full]"
```

--------------------------------

### Date-Window Comparison: backtest.suite_enabled with scenarios

Source: https://github.com/enarjord/passivbot/blob/master/docs/suite_examples.md

Defines a backtest suite with three scenarios covering different market regimes (bull, bear, mixed) by specifying start and end dates. Useful for evaluating a config across different market conditions.

```json
{
  "backtest": {
    "suite_enabled": true,
    "reducer": {"default": "mean"},
    "scenarios": [
      {"label": "bull_2021", "start_date": "2021-01-01", "end_date": "2021-12-31"},
      {"label": "bear_2022", "start_date": "2022-01-01", "end_date": "2022-12-31"},
      {"label": "mixed_2024", "start_date": "2024-01-01", "end_date": "2024-12-31"}
    ]
  }
}
```

--------------------------------

### Docker run with env-generated credentials and schema defaults

Source: https://github.com/enarjord/passivbot/blob/master/docs/container_deployment.md

Runs the live container using environment-generated credentials (PB_EXCHANGE, PB_API_KEY, PB_API_SECRET) and schema defaults for config. Also sets PB_APPROVED_COINS to a comma-separated list.

```bash
docker run --rm \
  -e PB_USER=bitget_01 \
  -e PB_EXCHANGE=bitget \
  -e PB_API_KEY=... \
  -e PB_API_SECRET=... \
  -e PB_APPROVED_COINS=BTC,ETH,SOL \
  passivbot-live:latest
```

--------------------------------

### Clone and switch to tagged release v8.1.0

Source: https://github.com/enarjord/passivbot/blob/master/docs/releases.md

Use to install the tagged release v8.1.0 instead of the default master branch. Run these commands before installing dependencies. A detached release checkout does not advance with git pull.

```bash
git clone https://github.com/enarjord/passivbot.git
cd passivbot
git switch --detach v8.1.0
```

--------------------------------

### Run Strategy Example CLI Smoke Test

Source: https://github.com/enarjord/passivbot/blob/master/docs/plans/v8_strategy_runtime_merge_readiness_plan.md

Runs a strategy example smoke test through the CLI to validate the branch with a specific strategy and date range. Acceptance requires the smoke to complete without errors.

```bash
./venv/bin/passivbot backtest configs/examples/ema_anchor.json -sd 2022-01-01 -ed 2022-01-07
```

--------------------------------

### Run gpu-proxy-benchmark cases for MPS measurements

Source: https://github.com/enarjord/passivbot/blob/master/docs/optimizing.md

Run the gpu-proxy-benchmark harness for comparable local MPS measurements. Use a fresh process per case and confirm no other optimizer is using the device; the harness uses fixed-seed in-memory synthetic data and never reads credentials or local caches.

```bash
passivbot tool gpu-proxy-benchmark --case ema-single-long
passivbot tool gpu-proxy-benchmark --case tm-single-long
passivbot tool gpu-proxy-benchmark --case tm-single-long-entry-ladder
passivbot tool gpu-proxy-benchmark --case tm-single-long-static-close
passivbot tool gpu-proxy-benchmark --case tm-single-long-close-ladder
passivbot tool gpu-proxy-benchmark --case tm-single-long-hsl
passivbot tool gpu-proxy-benchmark --case ema-multicoin-overhead
passivbot tool gpu-proxy-benchmark --case ema-multicoin-overrides
passivbot tool gpu-proxy-benchmark --case tm-multicoin-overhead
# Hold one candidate matrix constant while measuring dispatch chunking:
passivbot tool gpu-proxy-benchmark --case ema-single-long \
  --candidates 4096 --dispatch-batch-size 1024
```