home / skills / openclaw / skills / npm-proxy

npm-proxy skill

safe

This skill helps you manage Nginx Proxy Manager hosts, certificates, and access lists via REST API for provisioning, SSL, and status checks.

npx playbooks add skill openclaw/skills --skill npm-proxy

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.7 KB

---
name: npm-proxy
description: Manage Nginx Proxy Manager (NPM) hosts, certificates, and access lists. Use when the user wants to add a new domain, point a domain to a server/port, enable SSL, or check the status of proxy hosts.
---

# NPM Proxy Skill

Manage Nginx Proxy Manager (NPM) via its REST API.

## Configuration

Set the following environment variables:
- `NPM_URL`: The URL of your NPM instance (e.g., `https://npm.example.com`)
- `NPM_EMAIL`: Your NPM admin email
- `NPM_PASSWORD`: Your NPM admin password

## Usage

```bash
# List all proxy hosts
python scripts/npm_client.py hosts

# Get details for a specific host
python scripts/npm_client.py host <host_id>

# Enable/Disable a host
python scripts/npm_client.py enable <host_id>
python scripts/npm_client.py disable <host_id>

# Delete a host
python scripts/npm_client.py delete <host_id>

# List certificates
python scripts/npm_client.py certs
```

## Workflows

### Adding a new Proxy Host
To add a new host, use `curl` directly (the script is currently minimal).
Example payload for `POST /api/nginx/proxy-hosts`:
```json
{
  "domain_names": ["sub.example.com"],
  "forward_scheme": "http",
  "forward_host": "192.168.1.10",
  "forward_port": 8080,
  "access_list_id": 0,
  "certificate_id": 0,
  "ssl_forced": false,
  "meta": {
    "letsencrypt_email": "",
    "letsencrypt_agree": false,
    "dns_challenge": false
  },
  "advanced_config": "",
  "locations": [],
  "block_exploits": true,
  "caching_enabled": false,
  "allow_websocket_upgrade": true,
  "http2_support": true,
  "hsts_enabled": false,
  "hsts_subdomains": false
}
```

### Enabling SSL (Let's Encrypt)
1. List certs with `certs` to see if one exists.
2. Update the host with `certificate_id` and `ssl_forced: true`.

Overview

This skill manages Nginx Proxy Manager (NPM) hosts, certificates, and access lists via the NPM REST API. It helps add and update proxy hosts, point domains to servers/ports, enable SSL/Let's Encrypt, and check host or certificate status. The skill is configured using environment variables for the NPM URL and admin credentials.

How this skill works

The skill authenticates with your NPM instance and calls NPM REST endpoints to list, create, update, enable/disable, and delete proxy hosts and certificates. It can post payloads to /api/nginx/proxy-hosts to add domains, update certificate_id and ssl_forced to enable SSL, and query endpoints to list hosts or certificates. Use environment variables NPM_URL, NPM_EMAIL, and NPM_PASSWORD to connect securely.

When to use it

Add a new domain or proxy host that forwards to an internal server and port.
Point an existing domain to a specific server IP and port through NPM.
Enable or renew SSL using Let's Encrypt for a proxy host.
Check status and details of proxy hosts and available certificates.
Enable or disable hosts or remove obsolete proxy configurations.

Best practices

Set NPM_URL, NPM_EMAIL, and NPM_PASSWORD in a secure environment; avoid committing credentials.
Verify DNS for the domain before enabling Let's Encrypt to avoid certificate failures.
Test new proxy host configuration with http first, then enable ssl_forced after certificate is present.
Use access lists to restrict admin-only or internal endpoints exposed via proxy hosts.
Keep advanced_config empty unless you need custom Nginx directives to avoid config errors.

Example use cases

Create a proxy host for sub.example.com forwarding to 192.168.1.10:8080 with websockets and HTTP/2 enabled.
Switch an application from port 3000 to port 8080 by updating the forward_port on the proxy host.
Enable Let's Encrypt for a host: find certificate_id from cert list, update host with certificate_id and set ssl_forced true.
Temporarily disable a public-facing host during maintenance using the disable action.
List all certificates to audit expiring or unused Let’s Encrypt certs before renewal.

FAQ

What environment variables are required to connect?

Set NPM_URL to your NPM instance URL and NPM_EMAIL and NPM_PASSWORD to an admin account.

How do I enable SSL for a host?

Confirm a certificate exists via the cert list, then update the host with certificate_id and set ssl_forced to true.

Can I create hosts with a single API call?

Yes. POST to /api/nginx/proxy-hosts with the host payload including domain_names, forward_host, forward_port, and options like block_exploits.