Self-hosting Zespan

Self-hosted Zespan is available on the Enterprise plan. Traces, metrics, and AI analysis stay within your own infrastructure. Sign-in and account events (email address, IP address, user agent) are still sent to the Better Auth Infra service today, and any email, analytics or AI-provider keys you configure send data to those providers.

Self-hosting requires an Enterprise license. Contact enterprise@zespan.com to get started. You’ll receive a license key, Docker registry credentials, deployment guide, and onboarding support.

What you get with Enterprise self-hosting

Docker image

A signed Docker image pulled from the Zespan private registry. New versions are published with each release.

License key

A license key that activates your deployment. Included with your Enterprise agreement.

Data sovereignty

No events, traces, or AI results ever leave your infrastructure. Ideal for regulated industries and data-sensitive environments.

Dedicated support

A shared Slack channel with the Zespan engineering team for deployment help, upgrades, and escalations.

Infrastructure requirements

Zespan self-hosting requires standard cloud infrastructure. Exact specifications, configuration details, and architecture diagrams are provided in the private deployment guide sent to Enterprise customers. To discuss infrastructure requirements for your environment, contact enterprise@zespan.com.

Deployment

The full deployment guide — including environment configuration, database setup, migration steps, and Docker Compose templates — is provided after your Enterprise license is issued. To get your license and deployment package, contact enterprise@zespan.com with your organization name and expected trace volume.

Pointing the SDK at your self-hosted instance

When using the Zespan SDK against your self-hosted deployment, set baseURL to your API server’s URL:

TypeScript
Python

import { zespan } from "@zespan/sdk";

zespan.init({
  apiKey: "zsp_your_project_api_key",
  baseURL: "https://api.yourdomain.com",
});

import zespan

zespan.init(
    api_key="zsp_your_project_api_key",
    base_url="https://api.yourdomain.com",
)

Health checks and monitoring

Endpoint	Authentication	Use it for
`GET /health` (API)	None	Liveness. Returns `{ "status": "ok", "timestamp", "build" }`, where `build` identifies the running release. Called from inside the container (loopback) it also returns `credentialKey` (`ok`, `missing` or `invalid`; see `LLM_CONNECTION_SECRET`). Use it for container and Kubernetes liveness and readiness probes.
`GET /healthz` (web app)	None	Liveness of the web app. Returns `{ "status": "ok", "build" }`.
`GET /ready` (API)	None	Dependency check for dashboards, alerting, and external uptime monitoring. Returns `200` with `{"status":"ready"}` or `503` with `{"status":"not_ready"}`, and a `checks` object with one word per dependency (`ok`, `error`, `timeout`, or `stale`). The background-job check is advisory unless `READY_REQUIRE_WORKER=true`.
`GET /metrics` (API)	`Authorization: Bearer <METRICS_TOKEN>`	Prometheus metrics, including request durations and background-job queue depths. Returns `404` while `METRICS_TOKEN` is unset and `401` for a wrong token.

Don’t use /ready as a Kubernetes readiness probe. It checks shared dependencies, so a brief database or cache blip would mark every instance unready at once and drain the whole service. Keep probes on /health, and point an external uptime check at /ready instead.

Upgrading

Upgrade instructions and migration guides are included in the deployment package and sent with each new release. Enterprise customers are notified of new versions through their dedicated Slack channel.

Support

Enterprise customers have access to:

A dedicated Slack channel with the Zespan engineering team
Upgrade assistance and migration guides

Reach us at enterprise@zespan.com or through your shared Slack channel.

AI Providers (BYOK)

Deployment

Security & Compliance

Account

Self-hosting Zespan

What you get with Enterprise self-hosting

Docker image

License key

Data sovereignty

Dedicated support

Infrastructure requirements

Deployment

Pointing the SDK at your self-hosted instance

Health checks and monitoring

Upgrading

Support

​What you get with Enterprise self-hosting

Docker image

License key

Data sovereignty

Dedicated support

​Infrastructure requirements

​Deployment

​Pointing the SDK at your self-hosted instance

​Health checks and monitoring

​Upgrading

​Support

What you get with Enterprise self-hosting

Infrastructure requirements

Deployment

Pointing the SDK at your self-hosted instance

Health checks and monitoring

Upgrading

Support