On-Premise & Self-Hosting

Instead of using Gatana Cloud, you can run the entire Gatana stack yourself

Self-hosting is available as part of the Enterprise plan. Please reach out to your account manager or send us an email at [email protected]

Helm Chart

Helm Chart soruce is available at https://github.com/gatana-ai/gatana-helm

helm install gatana oci://ghcr.io/gatana-ai/charts/gatana \
  --namespace gatana \
  -f values.yaml

Why Self-Host?

Where Gatana Cloud stores and processes data, which sub-processors touch it and what crosses the EU border is set out in the guide An MCP gateway with EU data residency. Self-hosting is the option for organizations whose rules go further than that.

Self-hosting Gatana gives you complete control over the Gatana infrastructure. Gatana (the company) will never see any of your configuration or data. This is ideal for organizations with strict compliance requirements, data residency obligations, or those who prefer to keep all AI tool interactions within their own network.

Benefits

  • Data sovereignty — All data stays within your infrastructure, never leaving your network
  • Compliance — Meet regulatory and compliance requirements by controlling where data is processed and stored
  • Network isolation — Run MCP servers that access internal systems without exposing them to the internet

Trade-offs

  • No automatic updates — New features and security patches require manual upgrades
  • Infrastructure costs — You provision and pay for the compute, database, and networking resources

Configuration

The chart's values.yaml documents every setting. The choices that shape an install:

  • Object storage. Gatana needs two buckets, for uploaded files and for Runnable Code packages. storage.provider selects gcs (Google Cloud Storage, the default) or s3, which covers AWS S3 and S3-compatible stores such as MinIO or Ceph. For S3, set storage.s3.region, point storage.s3.endpoint at a compatible store (empty means AWS), and either name a credentials secret or rely on ambient credentials (IRSA, node role).
  • Encryption of stored secrets. kms.provider chooses what wraps the organization data keys: Google Cloud KMS, AWS KMS, or nothing. The default is none, which stores sensitive values protected only by disk encryption, so review this before production use. See Confidentiality for the table of values.
  • Persistent storage for servers. Persistent storage is offered only when workloads.storageClassName names a Kubernetes storage class fit for untrusted workloads. workloads.storageSize sets the size every volume gets. Left empty, the option stays hidden in the app.
  • Tailscale. Tailscale egress is offered only when workloads.tailscaleImage names the sidecar image, on a cluster whose admission policy lets a container hold NET_ADMIN. Left empty, the option stays hidden in the app.
  • Audit log retention. auditLogs.maxAgeDays sets how long to keep audit records, including credential and sandbox logs. The default is 180. Use 0 to keep all records, or a whole number of at least 30 days. Invalid values prevent startup. Cleanup runs from 02:00 to 04:00 UTC, with a 5 GiB limit on stored record details per run, checked after each batch. Large backlogs can take several nights. Super-administrators can change retention in Global Settings.
  • Glama registry search. The Add Server registry search also shows remote servers listed on Glama when glama.apiKey (or glama.apiKeySecret) provides a Glama API key. Left empty, only the official MCP registry is searched.
  • Email sender. email.from sets the sender for SMTP and SES, for example Gatana <[email protected]>. Left empty, the sender is Gatana <noreply@<baseDomain>>. With SES, AWS must accept the address. Without the chart, set SENDER_EMAIL. The older settings SMTP_FROM and SES_FROM still work and override SENDER_EMAIL.
  • OpenTelemetry tracing. The backend emits traces when the standard OTEL_* variables (set through backend.extraEnv) point at an OTLP endpoint, and tracing stays off otherwise. Spans cover each MCP request, the connection to the upstream server, and the tool call itself. The trace context travels to upstream MCP servers in the _meta field of the call (traceparent, tracestate, baggage), so spans from your own servers can join the same trace.

Single-tenant mode

In single-tenant mode, an installation serves one organization on its public URL, for example http://localhost:8080 or https://gatana.example.com. It does not need a wildcard DNS record or a wildcard certificate. The setting is SINGLE_TENANT_MODE. With Helm, set it through backend.extraEnv.

SINGLE_TENANT_MODEResult
Not set, and the public host is localhost or an IP addressOn, with the organization ID app
Not set, and the public host is a host nameOff: each organization is served on <organization>.<host>
An organization ID, for example acmeOn, with that organization ID
falseOff
  • The organization ID can have lowercase letters, digits and hyphens, and at most 40 characters.
  • An IP address as the public host requires single-tenant mode.
  • With an IP host and email enabled, set SENDER_EMAIL, for example Gatana <[email protected]>. An IP address cannot be an email domain.
  • With EMAIL_PROVIDER unset, copy the invitation link and give it to the user to set a password. The link is shown once and expires after 30 days. Password setup and reset links also go to the backend log. This includes links requested through "Forgot your password?" on the sign-in page. A new owner has no password. The dashboard asks them to set one in My Account.
  • Behind a reverse proxy that serves a plain HTTP public URL, set TRUST_PROXY=true. Without it, rate limits and audit records use the proxy's IP address for every visitor.
  • Set SINGLE_TENANT_MODE=false to keep existing <organization>.localhost URLs.
  • On a new install, the first visit opens the setup guide at /setup. Whoever opens it first creates the organization and becomes its owner. No other organization can be created.
  • All host names select the configured organization. Sign-in sends the browser to the public URL.
  • MCP clients connect to <public URL>/mcp.
  • The CLI needs the organization ID: gatana config login app --base-url http://localhost:8080.

If you enable or disable this mode on an existing installation:

  1. Sign in again and reconnect MCP clients. The OAuth issuer changes, for example from https://acme.gatana.example.com to https://gatana.example.com.
  2. Replace set-password links sent before the change. These links stop working.
  3. Update the redirect URIs at your SAML or OIDC identity provider. The SSO settings page shows the new URIs.
  4. Reload the app in open browser tabs to load the new server settings. The browser can use cached settings for up to one minute after the change.

Other organizations in the database are unavailable in single-tenant mode. The backend logs up to five of their IDs at startup.

Code Mode without Kubernetes

Code Mode runs agent code in a worker. With the Helm chart, Gatana starts a worker pod for each organization. Without Kubernetes, run a separate worker container. Add these settings to the Gatana container:

SettingValue
CODE_MODE_WORKER_URLWorker URL that Gatana can reach, for example http://gatana-worker:8080
CODE_MODE_CALLBACK_URLGatana URL that the worker can reach, for example http://gatana:3000. Set it if the worker cannot reach the public URL. An --internal network has no route to the public URL. In a worker container, localhost points to that container.

For example, with Docker:

# Keep the worker on a network shared only with Gatana
docker network create --internal gatana-worker

docker run -d --name gatana-worker --network gatana-worker \
  --read-only --cap-drop ALL --security-opt no-new-privileges --memory 256m \
  ghcr.io/gatana-ai/gatana-worker:<version>

# Start the Gatana container as usual, with these two settings added:
#   -e CODE_MODE_WORKER_URL=http://gatana-worker:8080
#   -e CODE_MODE_CALLBACK_URL=http://gatana:3000
docker network connect gatana-worker gatana
  • At startup, the backend logs the required worker version. Use that version of ghcr.io/gatana-ai/gatana-worker.
  • Do not publish the worker port. The worker runs all code that it receives.
  • All organizations in the installation share this worker. With the Helm chart, each organization has its own worker pod.
  • CODE_MODE_CALLBACK_URL requires single-tenant mode. Its host does not identify an organization. With several organizations, leave it unset. The worker calls each organization's public URL. Give the worker a route to these URLs; do not use an internal network in this case.
  • If a Kubernetes cluster is available, CODE_MODE_WORKER_URL takes priority over worker pods.
  • The setup guide shows Code Mode as found when CODE_MODE_WORKER_URL is set. If the worker does not respond, execute_code returns an error that names this setting.

Database migrations and upgrades

The backend applies database migrations at startup. A new Kubernetes release starts as follows:

  1. The new pod opens its port.
  2. The readiness check and all other requests return 503.
  3. The liveness check returns 200. The pod is running. Kubernetes waits for readiness before it sends traffic.
  4. The pod acquires a lock in Postgres.
  5. The pod applies each pending migration and records it in the migrations table.
  6. After the migrations, the readiness check returns 200 and the pod receives traffic.

During a rolling upgrade, old versions continue to serve requests while the new version starts.

Multiple replicas

You can deploy multiple replicas at the same time. One replica holds the migration lock. The others wait for it to finish.

Helm upgrades

An index on a large table, such as the audit log, can take many minutes to build.

  1. Allow enough time for the migration when you run helm upgrade --wait or use --atomic. For example, set --timeout 30m. If the pod stops during a migration, the next start retries migrations that have no record in the migrations table.
  2. Keep the chart's liveness probe. It reports the pod as alive throughout the migration. Do not replace it with a probe that fails after a fixed time.

Setting values

The backend checks settings that have a fixed list of values. An invalid value, such as EMAIL_PROVIDER=smpt, stops startup. Some older values still work:

SettingOlder valueRead as
EMAIL_PROVIDERnonedisabled
ENVIRONMENTproductionprod

On a self-hosted install, the backend accepts an unknown ENVIRONMENT value with a warning and uses prod.

Database requirements

SettingRequirement
SchemaThe default is public. Set POSTGRES_SCHEMA through backend.extraEnv.
PermissionsThe database user needs CREATE on the database to create the schema and the pgcrypto and pg_trgm extensions.
Semantic search (optional)A superuser must create the vector extension. Gatana can run without it.

Set DATABASE_MIGRATIONS_AT_START=false to disable migrations on startup.

Gatana behind a proxy

Configure the proxy to forward X-Forwarded-Host to the Gatana backend. These proxies do this by default:

  • Caddy
  • Traefik

For nginx, add these settings:

proxy_set_header Host              $host;
proxy_set_header X-Forwarded-Host  $host;
proxy_set_header X-Forwarded-Proto $scheme;

Interested?

We would be happy to work with you, you can reach us at [email protected].

Last updated on

On this page