QuantDinger

> QuantDinger can submit real orders when live trading is explicitly enabled. > Start with paper trading, use restricted API keys, and review the risk and > compliance requirements for your jurisdiction. This project does not provide > investment advice. ## Watch QuantDinger in action

## What QuantDinger is QuantDinger is an **open-source AI Trading OS** for independent traders, Python strategy authors, and small teams. Its local-first, self-hosted design keeps market data, strategy code, broker credentials, and deployment under the operator's control. The project combines: - multi-provider AI market research and analysis; - Python indicators and Strategy API V2 development; - server-side backtesting and experiment workflows; - paper and live execution across crypto exchanges and traditional brokers; - web, mobile H5, human API, Agent Gateway, and MCP access; - PostgreSQL-backed state, durable workers, audit logs, and optional monitoring. It is not a black-box signal service. Strategy code, risk settings, credentials, and deployment remain under the operator's control. ## What changed in v5 The v5 backend is organized around explicit runtime and operational boundaries: - the HTTP API no longer owns long-running trading or scheduler loops; - trading, scheduling, Celery jobs, and migrations run as separate processes; - Celery handles finite, retryable work while long-lived strategy runtimes stay in the trading worker; - cache Redis and durable job Redis use separate instances and eviction policies; - high-risk API contracts are represented in OpenAPI and protected by tests; - JSON logs, request IDs, Prometheus metrics, dashboards, and alert rules are available through an optional observability overlay; - the production overlay runs backend processes as a non-root user with a read-only root filesystem, dropped capabilities, and resource limits; - CI checks syntax, lint, tests, release gates, Compose files, dependencies, source security, secrets, API compatibility, version drift, and text encoding. The source version is declared in [`VERSION`](VERSION). Git release tags use the same semantic version with a leading `v`, for example `v5.0.1`. ## Architecture

The editable source is available as architecture-v5.svg.

The diagram above shows the complete product and process architecture. The runtime topology below focuses on container-to-container ownership and data flow. ``` … ``` One backend image is reused by several containers with different commands: | Process | Responsibility | | --- | --- | | `migration` | Applies the database schema and exits before application services start. | | `backend` | Handles HTTP, authentication, validation, and durable command submission. | | `trading-worker` | Owns strategy runtimes, pending orders, broker sessions, and reconciliation. | | `scheduler-worker` | Runs portfolio, deployment, payment, and signal schedules. | | `celery-worker` | Executes finite AI, backtest, experiment, report, and maintenance jobs. | | `celery-beat` | Dispatches periodic Celery tasks. | See [Backend process roles](docs/architecture/PROCESS_ROLES_AND_TASKS.md), [architecture](docs/architecture/ARCHITECTURE.md), and [concurrency model](docs/architecture/CONCURRENCY_MODEL.md) for the ownership rules. ## Quick start ### Option A: prebuilt images Prerequisites: Docker with Compose v2. Node.js and a local Python environment are not required. Linux or macOS: ```bash curl -fsSL https://raw.githubusercontent.com/OpenByteInc/QuantDinger/main/install.sh | bash ``` Windows PowerShell: ```powershell irm https://raw.githubusercontent.com/OpenByteInc/QuantDinger/main/install.ps1 | iex ``` The installer asks for the initial administrator credentials, generates the required secrets, downloads the GHCR Compose stack, and starts it. Open: - Web: - Mobile H5: - API health: ### Docker administrator and settings notes Detailed guides: [English](docs/deployment/ADMIN_AND_SETTINGS_TROUBLESHOOTING_EN.md) | [中文](docs/deployment/ADMIN_AND_SETTINGS_TROUBLESHOOTING_CN.md) On a fresh database, the backend creates the initial administrator from `ADMIN_USER`, `ADMIN_PASSWORD`, and optional `ADMIN_EMAIL`. Passwords are stored as hashes, never as plaintext. An existing PostgreSQL volume is not overwritten: the backend only replaces the untouched legacy `quantdinger` / `123456` administrator when a non-default administrator is explicitly configured. It never overwrites an account whose password was already changed, and it refuses to promote an existing account that already uses the requested username. Manual Docker deployments retain `quantdinger` / `123456` only for backward compatibility when the administrator variables are left at their defaults. This credential is not suitable for an internet-facing deployment; change it before first start or immediately after the first login. The one-command installer does not accept `123456` as the chosen password. The Settings UI writes runtime configuration to `/app/.env`. In the GHCR stack this is the host `backend.env`; in a source deployment it is `backend_api_python/.env`. Current backend images automatically give runtime UID `10001` ownership and keep mode `600`. Do not use `chmod 755` or recursive `777`: these files contain passwords and API keys, and `755` still does not grant write access to UID `10001` when root owns the file. Verify write access with: ```bash docker compose exec -u 10001:10001 -T backend \ sh -c 'test -w /app/.env && echo writable=yes || echo writable=no' ``` The hardened production override intentionally mounts `/app/.env` read-only. When using `docker-compose.production.yml`, manage configuration on the host and recreate the services instead of saving it from the Settings UI. See the [English guide](docs/deployment/ADMIN_AND_SETTINGS_TROUBLESHOOTING_EN.md) or [中文指南](docs/deployment/ADMIN_AND_SETTINGS_TROUBLESHOOTING_CN.md) for legacy-image recovery and rootless/NFS notes. ### Option B: source checkout ```bash git clone https://github.com/OpenByteInc/QuantDinger.git cd QuantDinger cp backend_api_python/env.example backend_api_python/.env cp .env.example .env ``` Before the first start, replace the example values in both environment files: | File | Required production values | | --- | --- | | `backend_api_python/.env` | `SECRET_KEY`, `CREDENTIAL_ENCRYPTION_KEY`, `ADMIN_USER`, `ADMIN_PASSWORD` | | `.env` | `POSTGRES_PASSWORD`, `REDIS_PASSWORD`, `CELERY_REDIS_PASSWORD`, `GRAFANA_ADMIN_PASSWORD` | Generate independent secrets with: ```bash python -c "import secrets; print(secrets.token_hex(32))" ``` Start the core stack from local backend source: ```bash docker compose up -d --build docker compose ps ``` The base stack does not start Prometheus, Grafana, or Alertmanager. This keeps the default open-source installation smaller. For detailed installation paths, Windows notes, China mirror settings, and PostgreSQL migration guidance, see [Installation troubleshooting](docs/deployment/INSTALL_TROUBLESHOOTING.md) and the [cloud deployment guide](docs/deployment/CLOUD_DEPLOYMENT_EN.md). ## Production deployment Validate secrets before starting a production stack: ```bash python backend_api_python/scripts/check_production_config.py \ --env-file .env \ --env-file backend_api_python/.env ``` Start the hardened runtime with optional observability: ```bash docker compose \ -f docker-compose.yml \ -f docker-compose.production.yml \ -f docker-compose.observability.yml \ up -d --build ``` Omit `docker-compose.observability.yml` when the host is resource-constrained or monitoring is provided externally. Production rules: - expose only a TLS reverse proxy on ports 80/443; - keep PostgreSQL, both Redis instances, Prometheus, Grafana, and Alertmanager off the public internet; - do not deploy with example passwords or empty encryption keys; - back up PostgreSQL and the durable `redis-jobs` volume; - keep cache Redis disposable and never use it as the Celery broker; - review worker health and application readiness after every deployment. The full checklist is in [Production hardening](docs/deployment/PRODUCTION_HARDENING.md). ## Local endpoints All published ports bind to loopback by default. | Service | Default URL | Purpose | | --- | --- | --- | | Web | | Desktop web client and same-origin API proxy. | | Mobile H5 | | Mobile web client and same-origin API proxy. | | Backend | | Direct API access and health endpoints. | | Grafana | | Dashboards; available only with the observability overlay. | | Prometheus | | Metrics storage and queries; optional. | | Alertmanager | | Alert grouping, silencing, and delivery; optional. | Container-only ports such as the job Redis and exporters are not published to the host. ## Observability The monitoring stack is optional by design: - **Prometheus** collects API, worker, PostgreSQL, and Redis metrics. - **Grafana** turns those metrics into operator dashboards. - **Alertmanager** groups alerts, manages silences, and sends notifications once a receiver is configured. Start it for local diagnostics without the production overlay: ```bash docker compose \ -f docker-compose.yml \ -f docker-compose.observability.yml \ up -d ``` Monitoring services stay on `127.0.0.1`. Use a VPN, SSH tunnel, or authenticated reverse proxy for remote administration. See [Observability](docs/deployment/OBSERVABILITY.md) for dashboards, alerts, retention, and receiver configuration. ## Security model - Broker credentials and MFA secrets are encrypted with a stable `CREDENTIAL_ENCRYPTION_KEY`. - Agent tokens are hashed, scoped, rate-limited, and audit-logged. - Agent trading is paper-only by default; live access requires both token and server-side authorization. - Long-running strategy ownership uses leases, heartbeats, and fencing tokens. - Production containers run without root privileges or Linux capabilities. - Host port defaults are loopback-only; public access should terminate at a TLS reverse proxy. Report vulnerabilities privately according to [SECURITY.md](SECURITY.md). Do not include credentials, account data, or exploitable details in public issues. ## Strategy and integration surfaces | Area | Current surface | | --- | --- | | Indicators | Python chart overlays, markers, bands, and signals. | | Strategies | Strategy API V2 intents, sizing, risk, backtests, and live runtime. | | Crypto | Binance, OKX, Bitget, Bybit, Gate, HTX, and adapter extensions. | | Traditional brokers | IBKR and Alpaca workflows. | | AI providers | OpenRouter, OpenAI-compatible APIs, Google, DeepSeek, Grok, MiniMax, and custom endpoints. | | Automation | Human API, Agent Gateway, MCP server, Celery jobs, schedules, and notifications. | Start with the [Indicator guide](docs/trading/INDICATOR_DEV_GUIDE.md), [Strategy guide](docs/trading/STRATEGY_DEV_GUIDE.md), and [Extension guide](docs/architecture/EXTENSION_GUIDE.md). ## AI agents and MCP The Agent Gateway is exposed under `/api/agent/v1`. The included MCP server lets clients such as Cursor, Claude Code, and Codex call approved tools without receiving broker credentials or administrator JWTs. Live trading through an agent requires all of the following: 1. a token with trading scope; 2. `paper_only=false` on that token; 3. `AGENT_LIVE_TRADING_ENABLED=true` on the server; 4. operator-configured limits and allowlists. See [MCP setup](docs/agent/MCP_SETUP.md), [Agent quick start](docs/agent/AGENT_QUICKSTART.md), and the [Agent OpenAPI document](docs/agent/agent-openapi.json). ## Development Backend development uses Python 3.12: ```bash cd backe