Auracle/Docs/Install

Install

Three minutes from curl to a running install. Pre-built Docker images, one project directory under ~/auracle/.

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 Forge pipeline.

Disk planning Historical bars from polygon.io plus 5y of OHLCV across a 500-symbol universe is roughly 8–15 GB. The Forge probe agent samples conservatively — expect ~2 GB of cached samples per scan.

One-line install

Run this on a fresh host:

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 + LLM-driven Forge agents.
`POLYGON_API_KEY`	Adds polygon.io to the Forge'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`.
`AURACLE_LICENSE_KEY`	Your Institutional license key (format `akey_…`). Community tier ignores it.
`AURACLE_LICENSE_SERVER_URL`	Where the install pings `POST /license/validate` on startup + every 6 hours. Defaults to the Auracle license server. Operators self-hosting their own license server override this to their Houston URL.

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 — 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.