# RLXBT Server — operating guide for AI agents

Canonical URL: https://rlxbt.com/server-agent.md

Read this document before installing or operating RLXBT Server. RLXBT Server is
a self-hosted, headless Rust engine for strategy research, backtesting,
robustness testing, reinforcement learning, and stateless live-signal
evaluation. It does not connect to an exchange or place orders.

## Machine-readable contract

```yaml
product: RLXBT Server
image: ghcr.io/sergio12s/rlxbt-server:0.2.7
platforms: [linux/amd64, linux/arm64]
default_base_url: http://127.0.0.1:8142
health: GET /api/health
discovery: GET /api/endpoints
agent_context: GET /api/ai-instructions
strategy_schema: GET /api/strategy-schema
mcp_sse: GET /api/mcp/sse
mcp_messages: POST /api/mcp/messages
authentication: "Authorization: Bearer $RLXBT_API_KEY"
execution_boundary: "RLXBT decides; the external agent owns exchange state, risk, and orders"
```

## Rules for the agent

1. Ask the user for permission before installing or changing a running service.
2. Never ask the user to paste the license or API key into chat. Ask them to put
   secrets in `.env` or an approved secret manager. Never print or upload them.
3. Keep port `8142` on loopback. For remote access use a VPN, SSH tunnel, or an
   authenticated TLS reverse proxy. Never expose raw port 8142 publicly.
4. Treat RLXBT as research and decision infrastructure, not as an exchange
   client. Never give it exchange credentials.
5. Before real orders, require replay parity, paper/shadow trading, independent
   position reconciliation, size/loss limits, stale-data checks, idempotency,
   and a kill switch in the execution agent.

## Install on Ubuntu

Requirements: Ubuntu 22.04/24.04, Docker Engine with Compose, and an RLXBT
license. The image is public; the license activates the engine.

```bash
mkdir -p rlxbt-server && cd rlxbt-server
curl -fsSLO https://rlxbt.com/downloads/rlxbt-server-compose.yml
curl -fsSLo .env https://rlxbt.com/downloads/rlxbt-server.env.example
chmod 600 .env
```

Stop here and ask the user to set `RLX_LICENSE_KEY` and a long random
`RLXBT_API_KEY` in `.env`. Then:

```bash
docker compose -f rlxbt-server-compose.yml pull
docker compose -f rlxbt-server-compose.yml up -d
docker compose -f rlxbt-server-compose.yml ps
curl --fail http://127.0.0.1:8142/api/health
```

Do not proceed if health is not successful. Useful diagnostics:

```bash
docker compose -f rlxbt-server-compose.yml logs --tail=200 rlxbt-server
docker inspect --format '{{.State.Health.Status}}' rlxbt-server-rlxbt-server-1
```

## Connect an agent

Set these values in the agent's secret/environment configuration, not in its
prompt history:

```bash
RLXBT_BASE_URL=http://127.0.0.1:8142
RLXBT_API_KEY=<same secret as the server .env>
```

Preferred transport is MCP over SSE when the client supports a URL plus custom
headers:

```text
URL:     ${RLXBT_BASE_URL}/api/mcp/sse
Header:  Authorization: Bearer ${RLXBT_API_KEY}
```

If the client cannot attach an authorization header to MCP SSE, use the REST
API. Send the bearer header on every request except the public health check.

For an agent running on another machine, keep Docker bound to loopback and open
an SSH tunnel instead of changing `RLXBT_PUBLISH_HOST`:

```bash
ssh -N -L 8142:127.0.0.1:8142 user@your-ubuntu-server
```

The remote engine is then available to that agent at
`http://127.0.0.1:8142` through the encrypted tunnel.

## Give the server a local dataset

Public OHLCV can be fetched through the engine. For a private user-owned file,
copy it into the persistent data volume and use the container path when calling
`load_dataset`:

```bash
docker compose -f rlxbt-server-compose.yml exec rlxbt-server \
  mkdir -p /var/lib/rlxbt/datasets
docker compose -f rlxbt-server-compose.yml cp ./BTCUSDT_1h.csv \
  rlxbt-server:/var/lib/rlxbt/datasets/BTCUSDT_1h.csv
```

The agent should then load `/var/lib/rlxbt/datasets/BTCUSDT_1h.csv`. Never copy
a dataset without the user's permission, and never send private data to a
third-party service.

## Mandatory discovery sequence

Every new agent session should perform this sequence instead of guessing
schemas or capabilities:

```bash
curl --fail "$RLXBT_BASE_URL/api/health"
curl --fail "$RLXBT_BASE_URL/api/endpoints" \
  -H "Authorization: Bearer $RLXBT_API_KEY"
curl --fail "$RLXBT_BASE_URL/api/ai-instructions" \
  -H "Authorization: Bearer $RLXBT_API_KEY"
curl --fail "$RLXBT_BASE_URL/api/strategy-schema" \
  -H "Authorization: Bearer $RLXBT_API_KEY"
```

The response from `/api/ai-instructions` is the engine-generated operating
context for the currently loaded data and license capabilities. Follow it.

## Research workflow

1. Load a user-approved local dataset with `load_dataset`, or fetch public
   market data with `fetch_market_data`.
2. Call `get_dataset_info` and `get_ai_instructions`. Only reference features
   that actually exist.
3. Call `get_strategy_schema`, form a falsifiable hypothesis, build exact JSON,
   and run `validate_strategy` before `ai_run_backtest`.
4. Include realistic commission and slippage. A frictionless backtest is not
   evidence of tradability.
5. Do not recommend a strategy from one backtest. Use walk-forward,
   Monte Carlo, sensitivity, and out-of-sample evidence when the license plan
   enables them.
6. Save and pin robust reports; clearly reject weak or overfit candidates.
7. For RL, keep a held-out test split and inspect both performance and action
   distribution before using `rl_predict`.

Useful MCP tools include `get_ai_instructions`, `load_dataset`,
`fetch_market_data`, `get_strategy_schema`, `validate_strategy`,
`ai_run_backtest`, `walk_forward`, `monte_carlo`, `sensitivity`, `portfolio`,
`list_reports`, `pin_report`, `rl_train`, and `rl_predict`. Discover the live
list from `/api/endpoints`; do not rely only on this summary.

## Live-signal workflow

RLXBT evaluates a validated rules strategy; the external execution agent owns
market data, feature calculations, authoritative position state, risk checks,
and exchange orders.

For each completed candle, call `POST /api/signal` with either a pinned
`report_id` or immutable `strategy_json`, plus the bar, every referenced
feature, and current position state. The result is `enter_long`, `enter_short`,
`exit`, or `hold`, with absolute TP/SL prices where applicable.

Before enabling orders:

- replay recent bars through the same endpoint and require event parity with
  the validation backtest;
- verify identical indicators, candle boundaries, timezone, costs, and
  completed-bar policy;
- reconcile the real exchange position before every call;
- begin in shadow/paper mode and then use minimum size;
- make order submission idempotent and keep an independent kill switch.

Never interpret a signal response as proof an order was executed. RLXBT does
not know the exchange order state.

## Upgrade and rollback

Back up the `rlxbt-data` and `rlxbt-cache` Docker volumes first. Then:

```bash
docker compose -f rlxbt-server-compose.yml pull
docker compose -f rlxbt-server-compose.yml up -d
curl --fail http://127.0.0.1:8142/api/health
```

After an upgrade, repeat the replay-parity test before re-enabling live orders.

Human installation page: https://rlxbt.com/server
Full agent specification: https://rlxbt.com/ai.md
MCP reference: https://rlxbt.com/docs/mcp