Skip to content
Zentalk Developer

Environments and base URLs

Zentalk exposes one public API host per environment; the mesh services run alongside it on fixed ports. This page maps every service to its address and health check.

Base URLs

Section titled “Base URLs”
Environment REST API WebSocket
Local development http://localhost:3001 ws://localhost:3001/ws
Production https://api.zentalk.chat wss://api.zentalk.chat/ws

REST endpoints live under the /api/v1/ prefix (the unversioned /api/ prefix is a deprecated legacy alias — see Versioning). The web client reads these from NEXT_PUBLIC_API_URL and NEXT_PUBLIC_WS_URL.

The API server validates its environment via ZENTALK_ENV: development, staging, production, or test/testing. staging maps internally to production behavior, and an empty value defaults to production.

Run the stack locally

Section titled “Run the stack locally”

From a checkout of the zentalk-web repository, start the full stack with Docker:

Start the local stack
docker compose -f docker-compose.dev.yml up -d

This brings up the API server, PostgreSQL, Redis, and the node services on the ports listed below. Verify with curl http://localhost:3001/health — see Health endpoints for the full check list.

Local development ports

Section titled “Local development ports”

As configured in docker-compose.dev.yml:

Service Port Purpose
Web app (Next.js) 3000 Reference client
API server (zentalk-api) 3001 REST + WebSocket gateway
PostgreSQL 5432 Primary datastore
Redis 6379 Cache, sessions, rate limiting
DHT bootstrap (zentalk-node) 9000 libp2p peer discovery
Relay 1 (zentalk-node) 9001 P2P message routing
Relay 2 (zentalk-node) 9002 Second relay (manual multi-relay setup; not in docker-compose.dev.yml)
Mesh storage P2P (zentalk-node) 9100 Erasure-coded distributed storage
Mesh Storage API (HTTP) 8080 Chunk upload/download API (the mesh-api binary defaults to 8080 via its -api-port flag; the MESH_API_PORT compose host-mapping variable is also 8080 — the federation demo maps host port 8081)

The root docker-compose.yml can additionally run Prometheus (host port 9093), Grafana (host port 3100), and node-exporter (host port 9101) under the optional monitoring profile.

Node-internal ports, health ports, and binary flag defaults are documented in Node binaries and ports — the canonical reference for zentalk-node services.

Health endpoints

Section titled “Health endpoints”

The API server exposes:

Endpoint Purpose
GET /health Basic liveness + status
GET /health/live Kubernetes liveness probe
GET /health/ready Readiness probe (dependencies reachable)
GET /health/detailed Extended dependency and subsystem report
GET /health/mesh Mesh-layer connectivity status
Verify a local stack
curl http://localhost:3001/health        # API
curl http://localhost:9092/health        # DHT bootstrap
curl http://localhost:9091/health        # Relay 1
curl http://localhost:8080/health        # Mesh storage

Node-level health endpoints also include http://localhost:8080/api/v1/node/stats and http://localhost:8080/api/v1/network/info on the Mesh Storage API — see the Mesh API reference.

Metrics

Section titled “Metrics”

The API server serves Prometheus metrics at GET /metrics, protected by a bearer token or restricted to localhost-only access.

On the Mesh Storage API, /metrics, /api/v1/node/stats, and /api/v1/node/info require authentication (Bearer token or wallet signature); /health and /api/v1/network/info remain public. Relay and bootstrap nodes serve unauthenticated /metrics on their health ports — see Node binaries and ports.

Rate-limit headers

Section titled “Rate-limit headers”

All environments return rate-limit metadata on API responses, and 429 responses additionally include Retry-After:

X-RateLimit-Limit: 100
X-RateLimit-Window: 60

See Rate limits for per-resource limits and handling guidance.

Next steps

Section titled “Next steps”