Auracle/Docs/Install

Install

The easiest way in: download Auracle Desktop. The launcher installs everything (Docker, the engine, the Auracle IDE) and opens straight into your workspace. Prefer the terminal? A manual Docker path is below.

Download Auracle Desktop

Auracle Desktop is the one thing you download: the home for the Auracle IDE, the engine, and every product we ship next. It checks for Docker (installs it if needed), pulls the images, brings up the stack, and launches the Auracle IDE. No compose files to edit, no keys to paste. Sign in with Google; backtest free, upgrade to Pro to go live.

macOS: .dmg (Apple Silicon + Intel)
Windows: .msi installer
Linux: .deb / .rpm / .AppImage

Download Auracle Desktop →

Requirements

You need a Linux or macOS host with Docker and Docker Compose v2. Windows works via WSL2.

Component	Minimum	Comfortable
CPU	4 cores	8 cores
RAM	8 GB	16 GB
Disk	50 GB SSD	200 GB SSD
Docker	24.x	26.x or later
OS	Linux x86_64 / macOS 13+	Linux x86_64

For live trading, you also need:

An IBKR account with IB Gateway or TWS reachable from the host (paper or live).
Optionally: Alpaca, ClearStreet, or Hyperliquid credentials.
An Anthropic API key if you want Jupyternaut and the full Auracle Agent pipeline.

Disk planning Historical bars from polygon.io plus 5y of OHLCV across a 500-symbol universe is roughly 8–15 GB. The Auracle Agent's probe step samples conservatively; expect ~2 GB of cached samples per scan.

Manual install (advanced)

Prefer the terminal, or running on a headless server without the launcher? Install the stack directly:

curl -fsSL https://raw.githubusercontent.com/SiixQuant/auracle-installer/main/install.sh | bash

The installer:

Verifies Docker and Compose v2 are present.
Creates ~/auracle/ and writes docker-compose.yml, .env.example, and an empty data/ directory.
Generates a random HOUSTON_API_KEY and a random Postgres password.
Pulls the images: siixquant/auracle-houston, siixquant/auracle-jupyter, siixquant/auracle-scheduler, siixquant/auracle-mcp, timescale/timescaledb:2.26.3-pg16, caddy:2.8-alpine.
Prints next steps (where to find the API key, how to start the stack).

Configuration

All configuration lives in ~/auracle/.env. The installer creates .env.example as a starting point. Copy it, edit the values you care about, and never commit the result.

cd ~/auracle
cp .env.example .env
$EDITOR .env

Required variables

Variable	Purpose
`POSTGRES_PASSWORD`	Database password (auto-generated).
`HOUSTON_API_KEY`	The `X-API-Key` for Houston's HTTP/JSON API.
`AURACLE_MCP_TOKEN`	Bearer token for the standalone MCP server on port 7777. Generate with `openssl rand -hex 32`.
`AURACLE_INSTALL_UUID`	A stable opaque ID for this install. Auto-generated.

Optional variables

Variable	Purpose
`ANTHROPIC_API_KEY`	Enables Jupyternaut + the LLM-driven Auracle Agent.
`POLYGON_API_KEY`	Adds polygon.io to the Auracle Agent's discovery pool.
`AURACLE_ALPACA_KEY` / `AURACLE_ALPACA_SECRET`	Alpaca data + execution.
`IBKR_HOST` / `IBKR_API_PORT`	Where IB Gateway / TWS listens. Defaults to `127.0.0.1:7497` (paper).
`AURACLE_FORGE_AMBIENT`	Set to `0` to disable the ambient AI context injection. Default `1`.

First run

Bring the stack up:

cd ~/auracle
docker compose up -d

Wait for the healthchecks (usually 30–45 s):

docker compose ps

NAME              IMAGE                  STATUS         PORTS
auracle-houston   siixquant/auracle-houston:latest  Up (healthy)   127.0.0.1:1969->1969/tcp
auracle-jupyter   siixquant/auracle-jupyter:latest  Up (healthy)   127.0.0.1:8888->8888/tcp
auracle-mcp       siixquant/auracle-mcp:latest      Up (healthy)   127.0.0.1:7777->7777/tcp
auracle-scheduler siixquant/auracle-scheduler:latest Up (healthy)
auracle-db        timescale/timescaledb:2.26.3-pg16 Up (healthy)   127.0.0.1:5432->5432/tcp
auracle-caddy     caddy:2.8-alpine                  Up (healthy)   0.0.0.0:80->80, 443->443/tcp

Four surfaces are now reachable:

Surface	URL	Auth
Web UI (Houston)	`http://localhost:1969/`	Sign in with the install admin email.
JupyterLab	`http://localhost:8888/`	Token from `docker logs auracle-jupyter`.
HTTP / JSON API	`http://localhost:1969/api/*`	`X-API-Key: $HOUSTON_API_KEY`
MCP server	`http://localhost:7777`	`Authorization: Bearer $AURACLE_MCP_TOKEN`

On first hit to the web UI you accept the EULA. After that you land on the dashboard.

Heads up Auracle uses ${VAR:?required} syntax in docker-compose.yml, so docker compose will refuse to start until .env exists and has the required variables. The installer creates one for you; only edit, never delete it.

Seed the providers registry

The providers registry is populated automatically on first boot, but you can refresh it manually:

auracle forge providers
# Lists the 14 bundled providers and the columns the catalog will use.

Verify the catalog API

curl -s http://localhost:1969/forge/catalog \
  -H "X-API-Key: $HOUSTON_API_KEY"
# {"datasets":[],"count":0}   — empty, but the endpoint is live.

Updating

Auracle releases follow semver. Updates ship as image tags; nothing on disk changes.

cd ~/auracle
docker compose pull
docker compose up -d

Schema migrations run automatically on every boot. New columns and tables land additively; no manual migrate command exists or is needed.

Rolling back

Pin the previous tag in docker-compose.yml and re-pull:

image: auracle/houston:2.0    # was :2.1
docker compose pull && docker compose up -d

The schema is forward-compatible across minor versions but not across majors. Don't roll back across a major boundary without first dumping ~/auracle/data/.

Tip Subscribe to release notifications on the installer repo. That's where every release tag is announced.

Troubleshooting

Common stumbles on first install, with fixes inline.

Symptom	Fix
`docker: command not found`	Install Docker Desktop, then re-run the installer.
`Cannot connect to the Docker daemon`	Docker Desktop isn't ready yet. Wait for the whale icon to settle.
`port is already allocated: 80` (or 443, 8888, 7777)	Stop whatever's using that port. `brew services stop httpd` is a common culprit on macOS.
Browser cert warning at `https://localhost`	Normal. Caddy generates a self-signed cert. Click Advanced → Proceed.
First image pull feels stuck	The Jupyter image is ~3.5 GB. A few minutes on slow connections is expected.
Can't log into Auracle	`docker compose logs houston \| grep ERROR`
MCP tools don't appear in Claude	Verify the bearer in your client config matches `.env` → `AURACLE_MCP_TOKEN`. Restart the MCP client.
`/ui/setup` shows "Setup token required"	Cloud / remote install: token is in `data/keys/.setup-token`. Paste as `?token=<TOKEN>` in the URL. Localhost browsers bypass automatically.
Container restart loop	`docker compose ps` + `docker compose logs <service> --tail 80`. Most loops are `.env` values missing; re-check the file.
Postgres "could not open relation" at startup	Transient TimescaleDB load race. `docker compose restart houston` typically clears it.

Still stuck? Full troubleshooting notes live in the installer README, and the installer issue tracker catches anything that bites multiple operators.