NangoHQ/nango

Overview

Nango is integration infrastructure for SaaS products and AI agents. It does three jobs. First, it owns the auth dance with third-party APIs: OAuth, API keys, basic auth, client credentials, JWT apps and more than a dozen other modes, all driven from one provider catalog. Second, it runs a credential-injecting proxy. Third, it hosts functions, TypeScript actions and syncs that you write against Nango’s SDK and that run on Nango’s infrastructure. Your backend or your agent then calls the Nango API, the Node client, or one of Nango’s MCP endpoints, and never handles a refresh token itself.

The provider catalog is data, not code. packages/providers/providers.yaml is a 29,500-line file with roughly 1,000 entries. Each entry names the auth mode, the authorize and token URLs, the proxy base URL with ${connectionConfig.*} templating, rate-limit headers, a pagination recipe, and optional hook scripts for webhooks and post-connection steps. Adding an API usually means adding YAML. Integration logic (which endpoints to sync, what an action does) is user-authored TypeScript that the CLI compiles and deploys.

The repository is a large Node/TypeScript monorepo with over 40 packages. It is licensed under the Elastic License 2.0, which is source-available but not OSI open source. It contains the whole cloud product, but the self-hosted Docker image is a deliberately reduced edition. That distinction matters more than anything else on this page (see Running it).

Architecture

flowchart LR
  APP["Your backend / agent"] --> SRV["server (Express API, MCP, Connect UI)"]
  SRV --> PRX["ProxyService"]
  PRX --> API["Third-party API"]
  SRV --> ORC["orchestrator + scheduler (Postgres queue)"]
  JOBS["jobs (task processor)"] -->|"dequeue"| ORC
  JOBS --> FLEET["fleet: runner nodes"]
  FLEET --> RUN["runner: node:vm exec"]
  RUN -->|"nango.get / proxy"| SRV
  RUN --> PER["persist"]
  PER --> REC["records (Postgres)"]
  SRV --> DB["Postgres + Redis"]

Component	Path	Role
API server	packages/server	Public/private REST API, OAuth callbacks, proxy, webhooks ingress, three MCP servers
Shared services	packages/shared	Connections, credential refresh, encryption, orchestrator client
Provider catalog	packages/providers	providers.yaml and providers.scopes.yaml, alias-resolving loader
Orchestrator	packages/orchestrator, packages/scheduler	Task/schedule service over Postgres (FOR UPDATE SKIP LOCKED)
Jobs	packages/jobs	Dequeues tasks and dispatches them to a runtime (runner fleet or Lambda)
Fleet	packages/fleet	Manages runner nodes on local processes, Render, Kubernetes or Lambda
Runner	packages/runner, packages/runner-sdk	Executes deployed function code; the nango object scripts call
Persist / records	packages/persist, packages/records	Writes sync records and logs; serves the record cache
CLI and clients	packages/cli, packages/node-client, packages/connect-ui	Author and deploy functions; call the API; embedded auth UI

How a request flows

Take an agent or backend calling nango.triggerAction("hubspot", "user-42", "create-contact", input):

1. API entry. The public route resolves the environment and calls executeAction. That function loads the connection and the provider config, resolves the deployed function, refuses disabled ones, opens an activity-log context, and calls the orchestrator client (action.service.ts).
2. Enqueue. triggerAction builds a task named after the environment, connection and action. Async actions go into a group with maxConcurrency: 1, so they run one at a time per environment. Sync actions are scheduled and awaited (orchestrator.ts). executeAction gives the task 30 seconds to start and 15 minutes to finish, then long-polls the task output (client.ts).
3. Schedule. The orchestrator stores tasks and schedules in Postgres. Due recurring syncs are picked with FOR UPDATE SKIP LOCKED, so several orchestrator instances can share the table (scheduling.ts).
4. Dequeue. In the jobs service, OrchestratorProcessor long-polls dequeue into a PQueue sized to its concurrency and reports failed tasks back (processor.ts). handler branches on task type: sync, abort, action, function, webhook or on-event (handler.ts).
5. Pick a runtime. startScript fetches the compiled script from local disk or remote storage and asks getRuntimeAdapter for a runner or Lambda adapter (start.ts, runtimes.ts). In production each team gets its own runner id, and if that runner cannot start the call falls back to a shared default runner (runner.ts).
6. Execute. The runner wraps the CommonJS bundle and runs it in a node:vm context. console is a no-op, string and WASM code generation are off, and require is limited to url, crypto, zod, botbuilder, soap and unzipper (exec.ts).
7. Call the API. Inside the script, nango.get/post/proxy goes back to the server’s ProxyService. That service checks base-URL overrides and plan capping, loads the integration and connection, refreshes credentials if needed, and sends the request with retries (proxy.service.ts). For syncs, batchSave sends records to persist.
8. Return. The runner reports the output, the task becomes SUCCEEDED, and the waiting API call returns the action result.

Key components

Provider catalog

loadProvidersYaml reads the YAML once and resolves alias: entries by shallow-merging the parent with overrides. This is how sandbox and regional variants avoid copying whole entries (index.ts). A typical entry, HubSpot, declares OAUTH2, a portalId connection field, three hook scripts (post-connection, pre-deletion, webhook routing), a rate-limit header and a cursor pagination recipe (providers.yaml). The proxy and nango.paginate() read these fields, so most per-API behaviour is configuration.

Credentials and refresh

Connection credentials are encrypted with AES-256-GCM in EncryptionManager.encryptConnection. If no encryption key is configured, shouldEncrypt() is false and credentials are stored as plain JSON (encryption.manager.ts). Refresh is guarded twice. Within one process, an in-flight map shares a single refresh promise. Across processes, a Redis lock is taken per connection with a 10-second TTL. The code’s own comment notes that this lock is not safe across several Redis instances (refresh.ts). Failed refreshes enter a cooldown, and connections are eventually marked refresh_exhausted.

MCP surfaces

The server exposes three MCP endpoints:

• /mcp serves one connection’s deployed actions as tools, selected with connection-id and provider-config-key headers.
• /session/:sessionId/mcp is for agent sessions.
• A separate management router exposes /mcp with tools for provisioning integrations, functions and syncs (routes.public.ts, L478-L482).

The agent-session server is the agent-oriented one. It registers four meta-tools: nango_tool_search, nango_execute, nango_proxy and nango_create_connection. It also registers every tool the session’s toolset allows, but it pages tools/list at 50 entries. Searchable-but-unlisted tools stay callable by name or through nango_execute (sessionServer.ts, L60-L154).

Webhooks

Incoming provider webhooks hit routeWebhook. It looks up the provider’s webhook_routing_script in a table of dozens of per-provider handler files, lets the handler map the payload to connections and to syncs that have onWebhook logic, and then forwards a signed copy to your own webhook URL if your plan allows it (webhook.manager.ts).

Extending it

• New API. Add a providers.yaml entry (auth mode, URLs, proxy config, optional pagination and hook script names). There is no per-provider TypeScript unless the API needs a webhook router or a post-connection hook.
• Functions. nango init, nango dev, nango dryrun and nango deploy (in packages/cli) compile TypeScript syncs and actions written against runner-sdk and push them to an environment. “Zero-YAML” functions export a typed object instead of a nango.yaml declaration. Syncs use batchSave, lastSyncDate and saveCheckpoint for incremental runs.
• Consumption. The Node client covers connections, proxy, triggerAction/triggerActionAsync, listRecords with cursor pagination, and connect sessions. Agents can use the MCP endpoints instead.

Running it

• Nango Cloud is the full product.
• Self-hosted Docker (docker-compose.yaml) runs nango-server, Postgres and Redis, with Elasticsearch optional for logs. It mounts providers.yaml into the container. The image deletes packages/jobs, packages/runner and packages/persist at build time (Dockerfile.self_hosted). A Docker run counts as isHosted, and flagHasScripts is true only for local, enterprise, cloud and test (detection.ts). The free self-hosted edition therefore gives you auth, the Connect UI and the proxy, but not syncs, actions or functions. Running those yourself requires the enterprise mode (NANGO_ENTERPRISE).
• Local development runs every service from the monorepo with RUNNER_TYPE=LOCAL, which spawns runner child processes.

Strengths and caveats

• Strength: breadth as data. About 1,000 providers live in one reviewed YAML file. Pagination and rate-limit hints sit beside auth, so the proxy and the SDK get per-API behaviour for free.
• Strength: production-grade auth plumbing. Per-connection refresh locking, refresh backoff and exhaustion tracking, encrypted credentials, and a white-label Connect UI.
• Strength: real job system. A Postgres-backed scheduler with heartbeats, timeouts and retries, per-team runner fleets on Kubernetes, Render or Lambda, and durable records with cursor reads.
• Caveat: self-host is auth + proxy only. The open image strips the function runtime, so the “1,000 APIs for your agent” story needs Cloud or an enterprise deployment.
• Caveat: node:vm is not a security boundary. The runner context receives host-realm Buffer, Error and setTimeout. Isolation comes from running each team on separate runner nodes in production. Outside production, every team shares the default runner, and production falls back to it when a team’s runner fails.
• Caveat: plaintext fallback. If you forget NANGO_ENCRYPTION_KEY, credentials are stored unencrypted.
• Caveat: licence and size. Elastic License 2.0 forbids offering Nango as a managed service. The codebase is large: dozens of packages, several datastores (Postgres, Redis, optional ClickHouse and Elasticsearch) and cloud-specific services in the same tree.

Sources: code at 8da0001, OpenDeepWiki wiki (36 pages), verified Q&A.