Kernel Docs

Deployment

Two deployment modes depending on how you want to run Kernel. The Evaluation Kit gives you a standalone Docker stack for local proof-of-concept. Self-hosted when data must stay inside your network — with an optional production stack that adds monitoring, backups, and TLS.

Hosted

No infrastructure to manage. Start evaluating immediately against the Kernel cloud API.

https://api.runtime-trust.com/health

Self-hosted

Run the full stack inside your network. Data never leaves. Use the Evaluation Kit for local trials. For production deployments, add monitoring (Prometheus/Grafana), daily Postgres backups, and Caddy reverse proxy with automatic Let's Encrypt TLS.

docker login kernel/runtime
docker pull kernel/runtime:0.2.0
docker compose up -d

# Production stack:
docker compose -f docker-compose.production.yml up -d

Self-hosted checklist

1. Contact Kernel for registry access
2. Set DATABASE_URL and DEMO_API_KEY
3. Pull the runtime image
4. Start `docker compose up -d`
5. Confirm `/health` returns ok
6. Run `./scripts/verify.sh`
7. Send a test evaluation
8. Review the result in the dashboard

What you need: Docker and a valid API key.

What starts: the API, dashboard, and Postgres together in your environment.

What happens next: point the SDK or API client at the local endpoint, start in Observation Mode, and only enable enforcement after the review flow is verified.

How access works: After approval, Kernel provides private registry credentials or a customer-specific deployment package. There is no public Git clone path for the self-hosted runtime.

Production requirements

The production stack adds Prometheus/Grafana monitoring, daily Postgres backups, and Caddy reverse proxy with automatic Let's Encrypt TLS.

Variable	Required	Description
`POSTGRES_PASSWORD`	Yes	PostgreSQL password.
`API_KEY`	Yes	API key for evaluation requests.
`API_DOMAIN`	No	Public API domain. Default `api.example.com`.
`DASHBOARD_DOMAIN`	No	Public dashboard domain. Default `dashboard.example.com`.
`MONITORING_DOMAIN`	No	Public Grafana domain. Default `monitoring.example.com`.
`ACME_EMAIL`	No	Email for Let's Encrypt certificate notifications.

Verify

Check the health endpoint after startup. If it returns ok, the service is ready for evaluations. If not, fix the database or network issue before proceeding.

curl http://localhost:8080/health

Variable	Required	Description
`PORT`	No	API server port. Default is `8080`.
`CORS_ORIGINS`	No	Allowed frontend origins.

Observation Mode is the default behavior. Start there first so you can confirm connectivity, data flow, and the review loop before enforcement is enabled. Do not skip this step.

Secrets management

For production, use a dedicated secrets provider instead of plain .env files:

# Doppler
doppler run -- docker compose -f docker-compose.production.yml up -d

# 1Password CLI
op run -- docker compose -f docker-compose.production.yml up -d

# Local env file (NOT committed)
docker compose --env-file .env.secret -f docker-compose.production.yml up -d

The .env.secret file is never committed to Git. For self-hosted evaluation-kit deployments, a .env file with POSTGRES_PASSWORD and API_KEY is sufficient.

Database

Kernel requires PostgreSQL 15+. The schema is applied automatically on startup as a safety net. For production:

Use a dedicated PostgreSQL instance (RDS, Cloud SQL, Azure Database, or self-hosted)
Configure regular backups
Set sslmode=require in the connection string for TLS
Use a connection pooler for high-traffic deployments

# Example connection strings
export DATABASE_URL="postgresql://user:pass@localhost:5432/kernel"
export DATABASE_URL="postgresql://user:[email protected]:5432/kernel?sslmode=require"

Migrations run automatically when the API starts. For production, run them explicitly so a failed migration doesn't block the container:

# Run migrations explicitly (recommended for production)
make migrate

# Or via Docker
docker compose run --rm kernel-api \
python3 -c "from storage import migrate_database; migrate_database(); print('Migration complete')"

Migrations are additive only — rollback requires a database restore.

Upgrading

# Pull the latest image
docker compose pull

# Run migrations explicitly before restart
make migrate

# Restart with new image
docker compose up -d

Rollback: if a deployment causes issues, pull a known-good image tag and recreate the containers. Database snapshots should be created before each upgrade:

# Before upgrading, dump the database
docker compose exec -T kernel-db pg_dump -U kernel \
| gzip > /backups/kernel_$(date +%Y%m%d_%H%M%S).sql.gz

Without a database snapshot, rollback is limited to the application layer — the schema cannot be reverted automatically.

Networking

Service	Port	Protocol	Purpose
Kernel API	8080	HTTP	API endpoint for evaluation
PostgreSQL	5432	PostgreSQL	Database (not exposed in production)
Dashboard	3000	HTTP	Web UI (optional — accessed via reverse proxy, not directly)

Security: API containers should not be directly exposed to the internet without a reverse proxy (nginx, Caddy, Cloudflare Tunnel). PostgreSQL should not be accessible from outside the Docker network. The dashboard, if deployed, sits behind the same reverse proxy.

# Example nginx reverse proxy
server {
listen 443 ssl;
server_name kernel.example.com;

location / {
proxy_pass http://kernel-api:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}

Authentication

Method	How it works
API key	`Authorization: Bearer <key>` header, validated against `API_KEY` / `DEMO_API_KEY`
Dashboard login	WorkOS OAuth (Google, GitHub, SSO) — hosted only

For self-hosted deployments, the API key is set via the API_KEY environment variable. For the evaluation kit, the default key is sk_live_abc123.

Verification checklist

After deploying in any mode, verify the following:

# 1. Health endpoint responds
curl http://localhost:8080/health
# {status}: {ok}

# 2. Evaluation works
curl -X POST http://localhost:8080/evaluate \
-H "Authorization: Bearer <key>" \
-H "Content-Type: application/json" \
-d '{"agent_id":"test","session_id":"test","action_type":"test","amount":0}'
# Returns a decision with scores

# 3. (Self-hosted / Evaluation Kit only) Dashboard loads
open http://localhost:3000

Once all three pass, the deployment is ready for observation-mode evaluation. Do not enable enforcement until you have confirmed data flow and the review loop end-to-end.