Self-hosting operations

Observe the system before you rely on it.

SkyTwin is currently a source-first developer preview, not a managed hosted product. These are the available local checks and metrics, with the limits called out rather than hidden.

Support boundary: a successful health probe shows process or dependency state; it does not establish signed-install evidence, public-beta readiness, account-connection support, or provider confidentiality.

Run locally

pnpm install
pnpm db:migrate
pnpm db:seed
pnpm dev

The usual development API listens on localhost:3100 and the dashboard on localhost:3200. The installer may bootstrap Node/pnpm and a hash-verified CockroachDB binary before starting services; inspect it before use. A separate local MCP server can be started on a chosen port:

TWIN_MCP_SERVER_PORT=4444 pnpm --filter @skytwin/twin-mcp-server start

Health probes

Endpoint	Meaning	Use it for
`GET /api/health/live`	The process is up.	Orchestrator liveness probe.
`GET /api/health/ready`	The database is reachable and the pool is not saturated. Returns `503` if the DB is unreachable or callers are queued.	Readiness gate and traffic admission.
`GET /api/health`	Legacy human-readable summary.	Manual inspection; prefer specific probes for automation.

curl -fsS http://localhost:3100/api/health/live
curl -fsS http://localhost:3100/api/health/ready

Prometheus metrics

GET /metrics exposes process-wide, Prometheus-compatible aggregates. It is read-only and unauthenticated so standard scrapers can use it; if that is too broad for your environment, put the API behind a reverse proxy that filters the route.

Metric	What it tells you
`skytwin_db_pool_total`, `_idle`	Database connection-pool capacity and idle headroom.
`skytwin_db_pool_waiting`	Queued callers. This is the pool-exhaustion canary; alert when it is above zero for more than 30 seconds.
`skytwin_process_uptime_seconds`	Process lifetime; repeated resets suggest crash looping.
`skytwin_process_heap_used_bytes`, `_total_bytes`, `_rss_bytes`	V8 and resident-memory consumption for leak detection.

scrape_configs:
  - job_name: skytwin
    metrics_path: /metrics
    static_configs:
      - targets: ['localhost:3100']
    scrape_interval: 15s

Recommended alerts and checks

Pool exhaustion: skytwin_db_pool_waiting > 0 for 30 seconds.
Crash loop: an uptime rate that repeatedly returns to zero in your monitoring window.
Memory: RSS above roughly twice your measured steady-state baseline.
Wire-format regression: curl -s http://localhost:3100/metrics | promtool check metrics should be silent.

A starter Grafana dashboard is available in source.

Current observability limits

Provider circuit-breaker state, decision rate, signal-ingress rate, and worker poll latency are not yet exposed through this API metrics endpoint. Do not build an alert as though their absence meant healthy behavior. Use logs, source-level diagnostics, and the canonical operations guide while that work remains incomplete.