Sorcha Quickstart

This is the agent-runnable setup path. A fresh Linux VM with Docker Engine ≥ 24 and PowerShell 7.5+ should reach a healthy gateway in under 15 minutes following only this document. Every prerequisite is named with a version constraint; every silent-failure mode in the setup script has been replaced with an explicit non-zero exit and a remediation hint.

Prerequisites

Tool	Minimum	Install
Docker Engine	24.0	https://docs.docker.com/engine/install/ (Linux) · Docker Desktop for macOS / Windows
Docker Compose v2	2.0	Bundled with Docker Desktop. On Linux: https://docs.docker.com/compose/install/linux/. The v1 standalone docker-compose is end-of-life and the setup script rejects it.
OpenSSL or Python 3	any	https://www.openssl.org/source/ · https://www.python.org/downloads/. Used to generate the JWT signing key.
Git (optional)	2.30	https://git-scm.com/downloads. Required only to clone this repo.
PowerShell (optional)	7.5	https://learn.microsoft.com/powershell/scripting/install/installing-powershell. Required only to run walkthroughs/.
Linux kernel (Docker's)	below 6.19, or 7.0.14+	MongoDB 8 crashes on kernels 6.19–7.0.13 (SERVER-121912); the setup script reads docker info's kernel and refuses one in that range. Under Docker Desktop this is the VM's kernel, not the host's.

Three TCP ports must be free on the host: 80, 443, 8080. The setup script probes them and exits non-zero with a remediation hint if any are bound.

Setup

git clone https://github.com/Sorcha-Platform/Sorcha.git
cd Sorcha
./scripts/sorcha-setup.sh

The script:

1. Checks every prerequisite in one pass. On failure, every gap is reported and the script exits non-zero with a single-line message of the form [sorcha-setup] missing prerequisite: <name> (≥ <version>); install via <link>.
2. Asks configuration questions (admin email, password, tenant name). Use --quiet to accept defaults non-interactively.
3. Writes .env with a freshly-generated JWT signing key.
4. Pulls images for every service.
5. Starts services via docker compose up -d.
6. Waits for /api/health to return 200 (timeout 60s). On timeout the script exits non-zero rather than printing a misleading success summary.

On success the final line is:

[sorcha-setup] success — gateway reachable at http://localhost. Verify with: curl -s http://localhost/api/health

Verify your installation

curl -s http://localhost/api/health

Expected JSON shape (exact field values vary):

{
  "status": "Healthy",
  "totalDuration": "00:00:00.0234567",
  "services": {
    "gateway": "Healthy",
    "blueprint-service": "Healthy",
    "wallet-service": "Healthy",
    "register-service": "Healthy",
    "tenant-service": "Healthy",
    "peer-service": "Healthy",
    "validator-service": "Healthy"
  }
}

If every entry under services is Healthy, the gateway is live and the underlying stack is up.

For the AI-discoverable surface, also try:

curl -s http://localhost/.well-known/openapi.json | head -20
curl -s http://localhost/.well-known/mcp.json
curl -s http://localhost/llms.txt

Common failures

Symptom	Likely cause	Fix
[sorcha-setup] missing prerequisite: docker	Docker not on PATH	Install per the table above and re-source your shell so docker is found.
[sorcha-setup] missing prerequisite: docker-daemon	Docker is installed but the daemon isn't running	Start Docker Desktop (Win/macOS) or sudo systemctl start docker (Linux).
[sorcha-setup] kernel X cannot run MongoDB 8 safely	Docker's kernel is 6.19–7.0.13, which crashes MongoDB 8 (SERVER-121912)	Upgrade the kernel to 7.0.14+ (e.g. the distro's latest HWE kernel) and reboot. Pinning an older MongoDB only disables the guard; it does not fix the crash.
[sorcha-setup] missing prerequisite: docker-compose-v2	Only the v1 standalone docker-compose is on PATH	Install Compose v2 (the docker compose plugin). v1 is past EOL.
[sorcha-setup] missing prerequisite: port-80-free	Another process is bound to port 80	sudo ss -tlnp | grep :80 to identify, then stop that process. Common culprits: Apache, nginx, IIS.
Gateway did not become healthy in the allotted window	One service is stuck or its dependencies aren't ready	docker compose logs -f to see which service is failing. Database container often needs more time on slow disks; re-run the script after a minute.
curl: (7) Failed to connect to localhost port 80	Setup script reported success but gateway is down	Check docker compose ps — gateway is Up but unhealthy is the most common shape. docker compose restart gateway clears most transient cases.
Walkthrough scripts fail with pwsh: command not found	PowerShell 7.5+ is not installed	Install per the optional row above. PowerShell is only needed for the walkthroughs/ end-to-end demos; the gateway and services run without it.

Next steps

• Agent integration. Read docs/mcp-server.md for the MCP connection guide. 67 tools across admin, designer, participant, and citizen slices — plus reference resources and guided prompts — are how an AI agent drives the platform.
• Walkthroughs. walkthroughs/TradeFinance/run.ps1 and walkthroughs/AssuredIdentity/run-agents.ps1 are runnable end-to-end demonstrations of the cryptographic-proof workflows the platform is designed for.
• Deeper reading. STANDARDS.md for the standards posture, the architecture overview for the system architecture, llms.txt for the LLM-led entry point.

Reporting setup-script issues

If the script fails in a way not covered above, capture the failing command and exit code with:

./scripts/sorcha-setup.sh 2>&1 | tee sorcha-setup.log

and open an issue at https://github.com/Sorcha-Platform/Sorcha/issues attaching sorcha-setup.log and the output of docker compose ps.