Multi-Service Tenants

What Are Multi-Service Tenants?

A tenant isn't just a single container. It's an isolation boundary that can contain multiple services. Services within the same tenant share a Kubernetes namespace, database credentials, and internal networking.

This is useful when your application has multiple components that need to work together, such as:

A frontend (Next.js) + a backend API (Express or FastAPI)
A web app + a background worker
A primary app + a documentation site

Adding Multiple Services

In the tenant creation wizard (Step 2), you can add additional services by clicking Add Service. Each service gets its own:

Source (GitHub repo or container image)
Framework and runtime configuration
Port
Resource size (Small / Medium / Large)

One service must be marked as primary: this is the service that gets the tenant's main subdomain.

How many services a tenant can hold depends on your plan: 2 on Free, 3 on Starter, 6 on Growth, and 12 on Scale.

Inter-Service Networking

Services within the same tenant can communicate over Kubernetes internal DNS:

Internal URL: http://{service-name}:80, accessible only within the tenant namespace
Public URL: https://{service-name}-{tenant-name}.staxa.dev, accessible from the internet

Staxa automatically injects STAXA_SERVICE_* environment variables into every service at deploy time, so your application code can reference other services without hardcoding URLs. For example, if your tenant has a service called api, every other service in the tenant gets:

STAXA_SERVICE_API_URL: the public URL
STAXA_SERVICE_API_INTERNAL_URL: the internal Kubernetes URL

Shared Environment Variables

Environment variables set in the Shared Env tab on the tenant detail page are available to all services in the tenant. This is the right place for database credentials, shared API keys, or any config that multiple services need.

Per-service environment variables can be set during creation in the wizard.

Network Rules

The Network tab on the tenant detail page controls traffic in and out of the tenant. Inbound rules let specific IP addresses reach a service or the database, and the egress mode decides which destinations your services can connect out to. See Network Rules & Database Access for details.