Getting Started

Stand up the Guardrails API, run the Proof Demo, and produce your first verifiable decision—in minutes, not sprints.

What you’re building

The Hexarch website is a static Astro build. The interactive Proof Demo is a React island that talks to the Guardrails API—a Python service that enforces policy, records decisions, and produces tamper-evident audit chains.

By the end of this guide, you’ll have:

Local development

1) Start the Guardrails API

From the repo root:

cd hexarch-guardrails-py
python -m hexarch_cli serve api --host 0.0.0.0 --port 8099 --init-db --enable-docs --cors-origins http://localhost:4000 --database-url sqlite:///./hexarch.db

Verify the API is running:

curl http://localhost:8099/health

You should see "status": "ok" and "database": "ok".

2) Start the website

From the repo root:

cd website
npm install
npm run dev

The website runs on http://localhost:4000.

How the Proof Demo calls the API

In development, the website proxies API requests:

This proxy is configured in website/astro.config.mjs. The same path works in production—just point it at your deployed Guardrails API.

Your first verifiable decision

Once both services are running:

  1. Navigate to /proof-demo
  2. Create a rule (this writes to the audit chain)
  3. Trigger an authorization decision via /authorize
  4. Download the JSON evidence artifact

That artifact is the proof. It includes the decision, the audit record, and the cryptographic chain fields—verifiable independently of the UI.

Troubleshooting

/health shows "database":"error"

The server is running, but it can’t connect to its configured database. On Windows, this often happens if your shell has DATABASE_URL set to a Postgres URL on a port that isn’t running.

Fix by overriding to SQLite explicitly:

python -m hexarch_cli serve api --host 0.0.0.0 --port 8099 --init-db --database-url sqlite:///./hexarch.db

403 Denied by policy

The API runs in default-deny mode. Create a policy that allows the demo actions before trying again. This is intentional—Hexarch treats “no explicit allow” as a denial, and records that decision too.

Next steps