nginx-proxy-manager-sdk: A TypeScript SDK for Dynamic Proxy Automation
Nginx Proxy Manager has been serving the self-hosted and Docker community for years. The UI is clean, SSL provisioning through Let’s Encrypt works out of the box, and managing reverse proxies is straightforward even for people who’ve never touched an nginx config file.
We use it across our infrastructure at AALA Solutions. It does its job well.
Where we needed more was automation. We build SaaS products where customers bring their own domains. Every new customer means a new proxy host, a new SSL certificate, domain verification. The UI handles this perfectly for manual setup. But when you need this to happen dynamically, from code, as part of a customer onboarding flow, you need an API layer.
So we built one and open-sourced it.
The SDK
nginx-proxy-manager-sdk is a TypeScript SDK that wraps the Nginx Proxy Manager API. Proxy host management, SSL certificate provisioning, custom location blocks, advanced nginx configuration. All available programmatically.
Zero production dependencies. Node.js 18+. Full TypeScript type definitions.
npm install nginx-proxy-manager-sdkSource on GitHub. MIT licensed.
Why Automation Matters
The UI is great for manual operations. But certain workflows need to happen without human intervention:
Custom domain onboarding. SaaS platforms that let customers use their own domains need to create proxy hosts and provision SSL certificates dynamically. This should be part of the signup flow, not a manual step someone handles later.
Infrastructure as code. When you manage dozens of services behind reverse proxies, you want proxy configurations in deployment scripts. Reproducible, version-controlled, automated.
CI/CD pipelines. Preview deployments, staging environments, branch-specific URLs. Each needs a proxy host with SSL. This fits naturally into automated pipelines.
Certificate lifecycle management. Monitoring certificates, triggering renewals, verifying domain reachability before provisioning. Automation makes this reliable instead of manual.
What It Looks Like in Practice
Proxy host with automatic SSL
import { NpmClient } from 'nginx-proxy-manager-sdk';
const client = new NpmClient({
baseUrl: 'http://127.0.0.1:81',
email: '[email protected]',
password: 'your-password',
});
const host = await client.proxyHosts.create({
domain_names: ['app.example.com'],
forward_scheme: 'http',
forward_host: '127.0.0.1',
forward_port: 3000,
certificate_id: 'new',
ssl_forced: true,
allow_websocket_upgrade: true,
});Setting certificate_id to 'new' tells Nginx Proxy Manager to auto-provision a Let’s Encrypt certificate for the domain.
Dynamic custom domain onboarding
async function onboardCustomDomain(customerDomain: string, appPort: number) {
// Verify the domain points to your server before requesting SSL
const reachability = await client.certificates.testHttp([customerDomain]);
if (reachability[customerDomain] !== 'ok') {
throw new Error(`${customerDomain} is not pointing to this server yet`);
}
// Create proxy host with auto SSL
return client.proxyHosts.create({
domain_names: [customerDomain],
forward_scheme: 'http',
forward_host: '127.0.0.1',
forward_port: appPort,
certificate_id: 'new',
ssl_forced: true,
http2_support: true,
block_exploits: true,
});
}The testHttp method verifies Let’s Encrypt can reach the domain before requesting the certificate. This avoids failed provisioning and wasted rate limits.
Wildcard SSL with DNS challenges
const cert = await client.certificates.create({
provider: 'letsencrypt',
domain_names: ['*.example.com'],
meta: {
dns_challenge: true,
dns_provider: 'cloudflare',
dns_provider_credentials: 'dns_cloudflare_api_token = your-token',
propagation_seconds: 30,
key_type: 'ecdsa',
},
});Both HTTP-01 and DNS-01 challenges are supported. Works with Cloudflare, Route53, DigitalOcean, and other DNS providers.
Path-based routing
await client.proxyHosts.create({
domain_names: ['app.example.com'],
forward_scheme: 'http',
forward_host: '127.0.0.1',
forward_port: 3000,
locations: [
{
path: '/api',
forward_scheme: 'http',
forward_host: '127.0.0.1',
forward_port: 8080,
},
{
path: '/ws',
forward_scheme: 'http',
forward_host: '127.0.0.1',
forward_port: 8081,
advanced_config: 'proxy_read_timeout 86400;',
},
],
});Single domain, multiple backends. Frontend on 3000, API on 8080, WebSocket on 8081.
Under the Hood
Zero dependencies. Uses native fetch from Node.js 18+. No axios, no node-fetch. Clean dependency footprint.
Auto-managed authentication. The SDK logs in on the first request and refreshes the token when it expires. You can also pass a Bearer token directly, or combine both where the token is tried first and credentials serve as fallback.
Retry logic for nginx reloads. Nginx Proxy Manager reloads nginx after configuration changes, which can drop active connections. The SDK detects these socket errors and retries with exponential backoff.
Input validation. Domain names are validated against characters that would break nginx’s server_name directive. Advanced config strings are checked for patterns that could corrupt the server block. Guardrails, not restrictions.
Timeouts that match reality. 30 seconds for standard API calls. 15 minutes for certificate operations, because Let’s Encrypt provisioning takes time, especially with DNS challenges.
Full TypeScript support. Every interface exported. snake_case properties match the API wire format. camelCase methods follow TypeScript conventions. Full IDE autocomplete.
Getting Started
Install from npm:
npm install nginx-proxy-manager-sdkFull documentation, examples, and type reference on GitHub.
Requires Node.js 18+ and Nginx Proxy Manager v2.x.
About AALA Solutions
AALA Solutions builds and maintains production software. 8+ years, 18,000+ hours delivered, 100+ projects ranging from enterprise ERPs to AI platforms. This SDK came from our own infrastructure work: automating reverse proxies, SSL, and custom domain management across the products we build and operate. We open-sourced it because Nginx Proxy Manager has been useful to us, and we wanted to support that ecosystem.