Self-host Nango

Nango offers a self-hosted deployment option for Enterprise customers. This guide covers deployment, scaling, updates, and other key operational details.

Architecture overview

Architecture components

Nango consists of several core services, each handling specific responsibilities:

Server (Node service): Powers the dashboard, API, proxy requests, and incoming/outgoing webhooks.
Orchestrator (Node service): Manages task scheduling and state tracking.
Jobs (Node service): Processes tasks and dispatches them to the Runner.
Runner (Node service): Executes integration code and interacts with external APIs.
Persist (Node service): Stores synced records and logs.
Postgres: Stores data for the control plane, API credentials, scheduled tasks, and synced records.
Object Storage (e.g. S3): Stores compiled integration code for execution by the Runner.
ElasticSearch: Stores execution data.
Redis: Caches system data, including socket information, token refresh locks, and rate limits.

Cloud vs. self-hosted architecture

The Nango architecture is largely the same for both Cloud and Enterprise self-hosting. This ensures self-hosted instances benefit from continuous dogfooding and load testing. The primary differences are:

In the Cloud version, the Runner service runs as isolated instances per customer.
The Postgres database is segmented by use case (control plane, task scheduling, synced records).

Features

All paid features available on Nango Cloud are also included in the Enterprise self-hosted edition.

Plan requirement

An Enterprise plan subscription is required. Enterprise Self-Hosted pricing contain a fixed annual license and maintenance fee, plus a fraction of the cloud usage-based fees since infrastructure is on the customer side.

Intended users

Inteded for large and/or regulated enterprises.

Deployment

By default, Nango is deployed using Helm charts. Custom deployments (e.g., ECS) are possible with our guidance.

Updates

Managed image updates are published on a two-month cadence, with occasional hotfixes as needed. Notifications about new releases will be posted to your dedicated Nango Slack channel. Managed image tags follow this format:

nangohq/nango:managed-{managed-release-version}-{application-version}-{commit-sha}

managed-release-version: Semantic versioning for the image lifecycle (major = breaking, minor/patch = features/fixes)
application-version: Semantic version of the Nango application baked into the image

Customers should pin their CLI version to the application-version specified in the tag for compatibility. You can find the latest version by checking the managed-manifest.json. See the full changelog for details on each release.

Cloud provider support

Supports all major cloud providers (AWS, GCP, Azure).

Recommended configuration

5 Node services (Server, Persist, Runner, Jobs, Orchestrator): 1 CPU, 2GB RAM per service
Postgres database: 2 CPU, 8GB RAM, 128GB storage
Redis data store: 128MB
ElasticSearch data store: 2 vCPU, 1GB RAM, 30GB storage
Object storage (e.g. S3): less than 500MB of storage

Scaling

The default configuration supports 1M+ sync/action executions per day (assuming ~2s execution time per action/sync). Auto-scaling is not provided out-of-the-box yet, but the default configuration scales far. We can guide you on configuring auto-scaling when needed. Bottlenecks mostly depend on:

Action/sync execution time: solved by scaling the Runner service vertically, then horizontally.
Cached records & size (for sync functions only): solved by scaling Postgres vertically.

Data storage

Postgres: Stores data for the control plane, API credentials, scheduled tasks, and synced records.
Object Storage (e.g. S3): Stores compiled integration code for execution by the Runner.
ElasticSearch: Stores execution data.
Redis: Caches system data, including socket information, token refresh locks, and rate limits.

Using existing data stores

Yes, Nango is flexible with data store setups. However, we recommend a separate instance for independent scaling.

Internet access requirements

Server: Required for proxy requests, credential management, and incoming/outgoing webhooks (inbound & outbound traffic).
Runner: Required for reading/writing data from external APIs during sync and action executions (outbound traffic only).

Exporting billing metrics

For usage-based billing, certain anonymous metrics must be exported to Nango. This can be done automatically or manually, depending on your preference. We’ll coordinate with your team during setup.

Exporting metrics & logs

Yes, metrics and logs can be exported to any monitoring tool using our OpenTelemetry Export add-on. Additional metrics and logs can be added upon request.

Email service

Nango uses emails for account verification, password reset, and sending invitations, etc… Any SMTP server can be configured to be used by Nango for these email communications.

Encryption key

You must provide your own encryption key via the NANGO_ENCRYPTION_KEY environment variable to enable encryption at rest. Without this key, credentials are stored unencrypted.

The encryption key must be a base64-encoded 256-bit (32-byte) key. Key rotation is not supported yet—changing the key after initial setup will cause decryption failures. Plan your key management accordingly.

Data retention configuration

The default retention period for deleted connections is 31 days. You can configure this via the CRON_DELETE_OLD_CONNECTIONS_MAX_DAYS environment variable.

Free self-hosting

A limited free self-hosting option is available for hobby projects. It is intended for lightweight deployments that need Auth and Proxy, without the managed features and support included with Enterprise self-hosting or Nango Cloud. For more details, see the pricing page or schedule a call to discuss the Enterprise self-hosted version.

Feature availability

Feature	Free self-hosted	Enterprise self-hosted / Nango Cloud
Auth	Yes	Yes
Proxy	Yes	Yes
Observability	Auth + proxy only	Full
OpenTelemetry export	No	Yes
Functions	No	Yes
Webhooks	No	Yes
MCP server	No	Yes
Customize auth branding	No	Yes
Role-based permissions	No	Yes
SAML SSO	No	Yes
Support SLA	No	Yes

Server URL, callback URL, and custom domains

Add server environment variables for the instance URL and port in the .env file or directly in your hosting provider:

NANGO_SERVER_URL=<INSTANCE-URL>
SERVER_PORT=<PORT>

The resulting OAuth callback URL is <INSTANCE-URL>/oauth/callback.

You can customize the callback URL by updating the “Callback URL” field in the “Environment Settings” tab in the Nango admin.

If you are using a custom domain, update NANGO_SERVER_URL to match it.

Connect UI

Nango Connect is available for self-hosted deployments in the main Docker image.

FLAG_SERVE_CONNECT_UI=true
NANGO_CONNECT_UI_PORT=3009
NANGO_PUBLIC_CONNECT_URL=<INSTANCE-URL>

Nango Connect is available by default at http://localhost:3009.

If you are using a custom domain, update NANGO_PUBLIC_CONNECT_URL to match it.

See Auth for the end-user connection flow.

Persistent storage

If you deploy with Docker Compose, the bundled database uses local container storage. This is not appropriate for production. Connect Nango to an external Postgres database by setting the database environment variables:

NANGO_DB_USER=<REPLACE>
NANGO_DB_PASSWORD=<REPLACE>
NANGO_DB_HOST=<REPLACE>
NANGO_DB_PORT=<REPLACE>
NANGO_DB_NAME=<REPLACE>
NANGO_DB_SSL=true

You can also use a database URL:

NANGO_DATABASE_URL=postgresql://user:password@host:port/dbname

Special characters in NANGO_DATABASE_URL must be URL encoded.

Nango is incompatible with connection poolers using pool_mode=transaction. Use a direct database connection or configure the pooler to use a different mode.

Records saved by sync functions can be persisted in a dedicated database. To use a dedicated records database, set RECORDS_DATABASE_URL:

RECORDS_DATABASE_URL=postgresql://user:password@host:port/dbname

Special characters in RECORDS_DATABASE_URL must be URL encoded. If it is not specified, records are stored in the main database.

Deploying with Render or Heroku automatically generates a persistent database connected to your Nango instance.

Securing your instance

Securing the dashboard

By default, the dashboard of your Nango instance is open to anyone who can access your instance URL. You can secure it with Basic Auth by setting the following environment variables and restarting the server:

FLAG_AUTH_ENABLED=false
NANGO_DASHBOARD_USERNAME=<PICK-A-USERNAME>
NANGO_DASHBOARD_PASSWORD=<PICK-A-PASSWORD>

Encrypting sensitive data

You can enforce encryption of sensitive data, including tokens, secret keys, and app secrets, by setting a 256-bit base64-encoded key:

openssl rand -base64 32

Set the generated value as NANGO_ENCRYPTION_KEY:

NANGO_ENCRYPTION_KEY=<BASE64-256BIT-KEY>

After you restart the Nango server, database encryption happens automatically. The encryption key cannot currently be modified after it is set.

NANGO_ENCRYPTION_KEY is also required for Connect UI. It is used to generate sessions for Connect UI. Without this key, Connect UI will not work.

Custom websockets path

The Nango server serves websockets from / by default for use by @nangohq/frontend during the login flow. To isolate websockets from the dashboard, set NANGO_SERVER_WEBSOCKETS_PATH:

NANGO_SERVER_WEBSOCKETS_PATH=</YOUR-WEBSOCKETS-PATH>

If you set a custom path, configure websocketsPath when initializing the Nango object in the @nangohq/frontend SDK:

import Nango from '@nangohq/frontend';

let nango = new Nango({ host: 'https://<YOUR-NANGO-INSTANCE>', websocketsPath: '</YOUR-WEBSOCKETS-PATH>' });

Telemetry

Telemetry on self-hosted instances is light by default. Nango tracks core actions at a high level and does not track sensitive information. You can disable telemetry with:

TELEMETRY=false

Logs

Nango uses Elasticsearch to store execution logs and power the logs UI. To keep free self-hosted deployments lighter, this stack is optional. To enable logs:

Host an Elasticsearch cluster.
Set NANGO_LOGS_ENABLED=true.
Configure the relevant NANGO_LOGS_ES_* environment variables.

Elasticsearch hosting options include:

Local: uncomment the service in docker-compose.yaml and run docker-compose up.
Elastic Cloud: use elastic.co.
Render: deploy an Elasticsearch instance with Render.

If NANGO_LOGS_ENABLED is false, logs are sent to stdout and can be viewed in your host logs.

Run and update Nango

To install Nango on a VM:

mkdir nango && cd nango
wget https://raw.githubusercontent.com/NangoHQ/nango/master/docker-compose.yaml
docker-compose up -d

To update Nango:

docker-compose stop
docker-compose rm -f
docker-compose pull
docker-compose up -d

If you are interested in the Enterprise self-hosting version, please get in touch with us in the community or book a demo.

Security - review data, encryption, and access controls.
Environments - organize dev, staging, and production setups.
Changelog - track changes that affect self-hosted upgrades.

Getting started

Guides

Reference

Architecture overview

Architecture components

Cloud vs. self-hosted architecture

Features

Plan requirement

Intended users

Deployment

Updates

Cloud provider support

Recommended configuration

Scaling

Data storage

Using existing data stores

Internet access requirements

Exporting billing metrics

Exporting metrics & logs

Email service

Encryption key

Data retention configuration

Free self-hosting

Feature availability

Server URL, callback URL, and custom domains

Connect UI

Persistent storage

Securing your instance

Securing the dashboard

Encrypting sensitive data

Custom websockets path

Telemetry

Logs

Run and update Nango

Getting started

Guides

Reference

Documentation Index

​Architecture overview

​Architecture components

​Cloud vs. self-hosted architecture

​Features

​Plan requirement

​Intended users

​Deployment

​Updates

​Cloud provider support

​Recommended configuration

​Scaling

​Data storage

​Using existing data stores

​Internet access requirements

​Exporting billing metrics

​Exporting metrics & logs

​Email service

​Encryption key

​Data retention configuration

​Free self-hosting

​Feature availability

​Server URL, callback URL, and custom domains

​Connect UI

​Persistent storage

​Securing your instance

​Securing the dashboard

​Encrypting sensitive data

​Custom websockets path

​Telemetry

​Logs

​Run and update Nango

​Related guides

Architecture overview

Architecture components

Cloud vs. self-hosted architecture

Features

Plan requirement

Intended users

Deployment

Updates

Cloud provider support

Recommended configuration

Scaling

Data storage

Using existing data stores

Internet access requirements

Exporting billing metrics

Exporting metrics & logs

Email service

Encryption key

Data retention configuration

Free self-hosting

Feature availability

Server URL, callback URL, and custom domains

Connect UI

Persistent storage

Securing your instance

Securing the dashboard

Encrypting sensitive data

Custom websockets path

Telemetry

Logs

Run and update Nango

Related guides