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.yamlWhy 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.providerselectsgcs(Google Cloud Storage, the default) ors3, which covers AWS S3 and S3-compatible stores such as MinIO or Ceph. For S3, setstorage.s3.region, pointstorage.s3.endpointat 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.providerchooses what wraps the organization data keys: Google Cloud KMS, AWS KMS, or nothing. The default isnone, 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.storageClassNamenames a Kubernetes storage class fit for untrusted workloads.workloads.storageSizesets the size every volume gets. Left empty, the option stays hidden in the app. - Tailscale. Tailscale egress is offered only when
workloads.tailscaleImagenames the sidecar image, on a cluster whose admission policy lets a container holdNET_ADMIN. Left empty, the option stays hidden in the app. - Audit log retention.
auditLogs.maxAgeDayssets how long to keep audit records, including credential and sandbox logs. The default is180. Use0to 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(orglama.apiKeySecret) provides a Glama API key. Left empty, only the official MCP registry is searched. - Email sender.
email.fromsets the sender for SMTP and SES, for exampleGatana <[email protected]>. Left empty, the sender isGatana <noreply@<baseDomain>>. With SES, AWS must accept the address. Without the chart, setSENDER_EMAIL. The older settingsSMTP_FROMandSES_FROMstill work and overrideSENDER_EMAIL. - OpenTelemetry tracing. The backend emits traces when the standard
OTEL_*variables (set throughbackend.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_metafield 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_MODE | Result |
|---|---|
Not set, and the public host is localhost or an IP address | On, with the organization ID app |
| Not set, and the public host is a host name | Off: each organization is served on <organization>.<host> |
An organization ID, for example acme | On, with that organization ID |
false | Off |
- 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 exampleGatana <[email protected]>. An IP address cannot be an email domain. - With
EMAIL_PROVIDERunset, 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=falseto keep existing<organization>.localhostURLs. - 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:
- Sign in again and reconnect MCP clients. The OAuth issuer changes, for example from
https://acme.gatana.example.comtohttps://gatana.example.com. - Replace set-password links sent before the change. These links stop working.
- Update the redirect URIs at your SAML or OIDC identity provider. The SSO settings page shows the new URIs.
- 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:
| Setting | Value |
|---|---|
CODE_MODE_WORKER_URL | Worker URL that Gatana can reach, for example http://gatana-worker:8080 |
CODE_MODE_CALLBACK_URL | Gatana 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_URLrequires 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_URLtakes priority over worker pods. - The setup guide shows Code Mode as found when
CODE_MODE_WORKER_URLis set. If the worker does not respond,execute_codereturns an error that names this setting.
Database migrations and upgrades
The backend applies database migrations at startup. A new Kubernetes release starts as follows:
- The new pod opens its port.
- The readiness check and all other requests return
503. - The liveness check returns
200. The pod is running. Kubernetes waits for readiness before it sends traffic. - The pod acquires a lock in Postgres.
- The pod applies each pending migration and records it in the
migrationstable. - After the migrations, the readiness check returns
200and 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.
- Allow enough time for the migration when you run
helm upgrade --waitor use--atomic. For example, set--timeout 30m. If the pod stops during a migration, the next start retries migrations that have no record in themigrationstable. - 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:
| Setting | Older value | Read as |
|---|---|---|
EMAIL_PROVIDER | none | disabled |
ENVIRONMENT | production | prod |
On a self-hosted install, the backend accepts an unknown ENVIRONMENT value with a warning and uses prod.
Database requirements
| Setting | Requirement |
|---|---|
| Schema | The default is public. Set POSTGRES_SCHEMA through backend.extraEnv. |
| Permissions | The 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