This helper repository provides an interactive, zero-dependency command-line installer designed to deploy the full CoReason tripartite swarm in a local development environment.
It handles host capability detection (NVIDIA GPUs & CDI device configurations), environment variable projection (.env), local PKI HTTPS integration (Caddy), and container orchestration (Docker Compose).
Before running the installer, ensure you have:
- Docker & Docker Compose (installed and running).
- NVIDIA Container Toolkit (optional, required only for local GPU hardware acceleration).
- Python 3.14+ (optional, the wrapper script will automatically bootstrap it via
uvif missing).
Clone this repository and run the bootstrap script appropriate for your operating system.
git clone https://github.com/CoReason-AI/coreason-installer.git
cd coreason-installer
chmod +x install.sh
./install.shgit clone https://github.com/CoReason-AI/coreason-installer.git
cd coreason-installer
.\install.ps1The installer supports several parameters to customize your deployment. You can pass these directly to the wrapper scripts:
| Argument | Description | Default |
|---|---|---|
--target-dir PATH |
Workspace path where configurations, volumes, and assets will be written. | . (Current directory) |
--hf-token TOKEN |
Hugging Face token required for GPU gating checks. | Prompts if GPU is detected |
--no-gpu |
Run in CPU-only mode even if an NVIDIA GPU is found. | False |
--timeout SECONDS |
Seconds to wait for the platform services to start and respond. | 90 |
Deploy to a dedicated folder with CPU-only mode:
./install.sh --target-dir ~/coreason-workspace --no-gpuThe installer prompts you to select a Network Egress Profile depending on your organization's security posture. This determines whether the container networks are fully isolated (internal: true in Docker Compose) or permitted to reach external resources.
| Profile | Compose network (swarm-mesh) |
Gateway network (sensory-gateway) |
Use Case |
|---|---|---|---|
Air-Gapped / Sovereign (air-gapped) |
internal: true (Isolated) |
internal: true (Isolated) |
Highly secure offline environments. Requires pre-loaded Docker images and local cache volumes for LLM weights. |
Hybrid / Model Egress (hybrid) |
internal: true (Isolated) |
internal: false (Permitted) |
Default state database remains isolated. The runtime API and Caddy gateway can contact external model providers or OIDC endpoints. |
Fully Connected (connected) |
internal: false (Permitted) |
internal: false (Permitted) |
Standard development environment with full outbound access. |
For Hybrid or Fully Connected deployments behind an enterprise next-generation firewall (NGFW), you must configure FQDN (Fully Qualified Domain Name) filtering to whitelist egress traffic. IP-based filtering is discouraged due to dynamic IP rotation in cloud infrastructure.
Required during the install and update phases to pull platform images:
- GitHub Container Registry (GHCR):
ghcr.io(HTTPS Port 443)pkg-containers.githubusercontent.com(HTTPS Port 443)
- Docker Hub (Base runtime and database images):
registry-1.docker.io(HTTPS Port 443)auth.docker.io(HTTPS Port 443)index.docker.io(HTTPS Port 443)production.cloudflare.docker.com(HTTPS Port 443)
Required by the local cognitive engine (sglang) or runtime to download open weights at boot:
huggingface.co(HTTPS Port 443)cdn-lfs.hf.co(HTTPS Port 443 - Large File Storage CDN redirect)cdn-lfs-us-1.hf.co(HTTPS Port 443)cdn-lfs-eu-1.hf.co(HTTPS Port 443)cas-bridge.xethub.hf.co(HTTPS Port 443)
Required by dex to authenticate users against corporate identity provider (IdP) systems:
- Microsoft Entra ID:
login.microsoftonline.com(HTTPS Port 443) - Okta Tenants:
*.okta.com(HTTPS Port 443) - Google Identity:
accounts.google.com(HTTPS Port 443)
Required if the runtime delegates inference to managed cloud backends instead of local GPU engines:
- OpenAI API:
api.openai.com(HTTPS Port 443) - Anthropic Claude API:
api.anthropic.com(HTTPS Port 443) - Google Cloud Vertex AI:
*.googleapis.com,us-central1-aiplatform.googleapis.com(HTTPS Port 443) - AWS Bedrock endpoints:
bedrock.*.amazonaws.com(HTTPS Port 443)
Tip
Zero-Public-Egress Best Practice (Private Endpoints): For enterprise cloud deployments in AWS or GCP, do not open public internet egress to access cognitive APIs. Instead, use AWS PrivateLink (Interface VPC Endpoints) for AWS Bedrock or Google Private Service Connect (PSC) for Vertex AI. This routes API calls entirely within the cloud vendor's private backbone, maintaining compliance and avoiding egress firewall overhead.
Upon completion, the installer configures and spawns the following container stack:
- Ingress Gateway (Caddy): Exposes Ports
80and443to route requests via HTTPS. - Identity Provider (Dex): Exposes Port
5556for federated OIDC callbacks. - CoReason Runtime API: Exposes Port
8000for FastAPI telemetry streams. - Workflow Orchestration (Temporal): Exposes Port
7233(gRPC) and Port8233(dashboard). - PostgreSQL: State database backing Temporal.
- Cognitive Engine (SGLang): Exposes Port
30000(spawned only under thegpuprofile).
When executed, the installer writes the following files to your target workspace:
target-workspace/
├── caddy_data/ # Caddy data directory containing auto-generated local certificates
│ └── caddy/pki/authorities/local/root.crt # Caddy Root CA Certificate
├── data/
│ ├── lancedb/ # Vector Database storage (chown 10000:10000)
│ ├── bronze/ # Ingested datasets storage (chown 10000:10000)
│ ├── silver/ # Standardized ontology ledger (chown 10000:10000)
│ ├── gold/ # Curated golden assets (chown 10000:10000)
│ └── plugins/ # Actuator WASM plugins (chown 10000:10000)
├── .env # Hardware-customized environment properties
├── compose.yaml # Docker Compose configuration spec
├── Caddyfile # Caddy ingress reverse proxy rules
└── dex-config.yaml # Dex client configurations