Getting started

Obsidian discovers cryptographic assets across your repositories, scores post-quantum migration readiness, and exposes that evidence through a dashboard, a REST API, and a read-only MCP server. This page walks the fastest path to your first results.

New to Obsidian? The Overview explains what it does and what it detects, and Security and data handling covers where your data goes and the trust boundaries between components.

1. Install with Docker

Docker Compose is the default way to run Obsidian — it brings up the API, the dashboard, and a scanner node in one stack.

Obsidian is in private beta. Request access to get the repository and container images, then create your environment file:

cp .env.example .env

Set at least CRYPTO_DISCOVERY_CSRF_SECRET (random, at least 32 bytes) and CRYPTO_DISCOVERY_SECRET_KEY (a base64-encoded 32-byte key). Then start everything, including the bundled scanner node:

docker compose --profile runner up -d --build

Full options, the production overlay, and reverse-proxy setup are in Deploy with Docker.

2. Create your admin login

Open http://localhost:3000 and go to /login. On an empty database, the first visit is the initial-admin setup. It needs a one-time token — set CRYPTO_DISCOVERY_INITIAL_ADMIN_SETUP_TOKEN in .env, or read the generated token from the API logs:

docker compose logs api

3. Add something to scan

Pick the path that matches your repositories:

• A public GitHub repo (fastest). Paste its URL in the dashboard. The bundled scanner node picks up the discovery job and scans it automatically.
• Private repositories. Connect a GitHub App or a fine-grained PAT — see Connect GitHub repositories.
• A local folder. Scan it directly with the CLI — see Scan a local repository.

4. Explore the results

Open the dashboard to see your crypto estate, exposure, inventory, and compliance posture. Read the dashboard explains each view, and Export a CBOM covers the CycloneDX output for downstream tooling.