3X-UI VPS

intent

Deploy a hardened 3X-UI proxy server on a VPS with the control panel and subscription server isolated to loopback, nginx terminating TLS on public ports 80/443, Xray VLESS running over XHTTP behind nginx, and UFW blocking all inbound except SSH/HTTP/HTTPS. Use this skill when the user explicitly asks to deploy 3X-UI from scratch, repair an existing deployment, lock down the panel and subscription server, tunnel the panel over SSH for safe access, bootstrap a new VLESS inbound, add clients to an existing inbound, or run OS and container updates. Do not use this skill for ad-hoc config edits or manual server mutations outside the bundled scripts.

inputs

Collect these before running any workflow:

• SSH target: root@hostname or equivalent, with SSH key or password auth confirmed
• Optional plain-text SSH password if the host requires password authentication
• Public domain name pointed at the VPS (must resolve from the VPS itself, not just the operator workstation)
• Optional ACME contact email for certificate renewal notifications
• Panel admin username and password (chosen by the operator, not auto-generated)
• Optional local tunnel port for panel SSH access (default 12053)
• Target host OS: Ubuntu 20.04 LTS or later, or Debian 11+. Confirm apt is available and the host has outbound internet access for Docker downloads, ACME issuance, and 3X-UI API calls.

External connections:

• Docker Hub: required for pulling 3X-UI and nginx images. Set up using curl -fsSL https://get.docker.com -o get-docker.sh and sh ./get-docker.sh on the target host.
• Let's Encrypt / ACME: required for TLS certificate issuance. No API key needed; DNS must resolve from the VPS for validation. Provide optional --acme-email for renewal notifications.
• SSH access: all operations tunnel through SSH to root@target. Scripts wrap SSH with optional password auth via --ssh-password parameter.

Operator workstation prerequisites:

• bash, python3, ssh client, dig command
• network connectivity to the target VPS on port 22 (SSH)
• ability to store and pass SSH password as a plain-text parameter (insecure but often unavoidable for password-auth-only hosts)

procedure

Step 1: Preflight checks

Before mutating the host, confirm these assumptions:

1. Log in to the VPS and check that the public domain resolves from the server itself:

   ssh <target> 'dig +short <your-domain>'
   

   If the domain does not resolve from the server, stop and correct DNS before proceeding.

2. Confirm SSH auth method (key or password):

   ssh -v <target> 'echo ok' 2>&1 | grep -i 'auth\|permission'
   

3. If the VPS already has a certificate for the same domain, confirm that the bootstrap script will reuse it instead of failing on "Domains not changed" ACME errors.

4. If this is a repeat deployment, stop any existing 3X-UI containers:

   ssh <target> 'docker compose -f /opt/3x-ui/docker-compose.yml down 2>/dev/null || true'
   

Inputs to step 1: SSH target, domain, optional SSH password.

Outputs from step 1: confirmation that DNS resolves, SSH works, and no conflicting containers exist.

Step 2: Bootstrap the host

Run the primary deployment script to install Docker, nginx, ACME, Docker Compose stack, and firewall rules:

./scripts/bootstrap-host.sh \
  --host root@example-vps \
  --ssh-password 'host-password' \
  --domain vpn.example.com \
  --panel-username admin \
  --panel-password 'panel-secret' \
  --acme-email 'admin@example.com'

This script:

• installs Docker via get.docker.com
• installs nginx and certbot for ACME
• creates /opt/3x-ui/ with Docker Compose configuration
• runs docker compose up -d to start 3X-UI, with panel bound to 127.0.0.1:2053 and subscription server on 127.0.0.1:2096
• issues a TLS certificate for the public domain
• configures nginx to listen on public 80/443, forward HTTP to HTTPS, and proxy the Xray backend on a secret path to 127.0.0.1:1234
• applies UFW firewall rules to allow only SSH (22), HTTP (80), and HTTPS (443) from the internet
• stores bootstrap parameters in /opt/3x-ui/bootstrap.env for future reference

Inputs to step 2: host, SSH password, domain, panel username, panel password, optional ACME email.

Outputs from step 2: Docker running, 3X-UI panel isolated to loopback, nginx on public 443, UFW active.

Step 3: Verify the deployment

Run remote verification commands to confirm the stack is healthy:

ssh <target> 'ss -ltnp | egrep ":2053 |:2096 |:1234 "'
ssh <target> 'docker compose -f /opt/3x-ui/docker-compose.yml ps'
ssh <target> 'curl -I http://127.0.0.1:2053/'
ssh <target> 'ufw status numbered'

Expected output:

• 127.0.0.1:2053 and 127.0.0.1:2096 listening (panel and subscription server, loopback only)
• 127.0.0.1:1234 listening (Xray backend inbound)
• 0.0.0.0:80 and 0.0.0.0:443 listening (nginx, public)
• curl -I returns 404 or similar (panel is responding)
• ufw status numbered shows allow rules for 22, 80, 443

Inputs to step 3: SSH target.

Outputs from step 3: confirmation that listeners are correct and no unexpected ports are open.

Step 4: Open the panel tunnel

Keep the 3X-UI panel SSH-only. Use the tunnel script to forward the panel to your local machine:

./scripts/open-panel-tunnel.sh \
  --host root@example-vps \
  --ssh-password 'host-password' \
  --local-port 12053 \
  --panel-port 2053

Then open http://127.0.0.1:12053 in your browser to access the panel UI.

The script:

• opens an SSH local port forward from your localhost:12053 to the remote 127.0.0.1:2053
• holds the tunnel open until you press Ctrl+C
• does not require the panel to be public

If the tunnel fails with an immediate SSH disconnect, stop other parallel SSH sessions to the same host, wait 10 seconds, and retry as a single tunnel.

Inputs to step 4: host, SSH password, local port, panel port.

Outputs from step 4: SSH tunnel running, panel accessible on http://127.0.0.1:12053.

Step 5: Bootstrap the first inbound

Create one VLESS inbound over XHTTP behind nginx using the bootstrap script:

python3 scripts/bootstrap-inbound.py \
  --panel-url http://127.0.0.1:12053 \
  --username admin \
  --password 'panel-secret' \
  --public-domain vpn.example.com \
  --backend-port 1234 \
  --path /xhttp-secret-path

This script:

• logs in to the 3X-UI panel API
• creates one VLESS inbound configured for XHTTP transport on the backend
• binds the backend inbound to 127.0.0.1:1234
• stores the secret path (must match the nginx config)
• prints a ready-to-share vless:// client URL with the public domain and path

The client-facing transport is TLS (because nginx terminates TLS on 443). The backend inbound behind nginx stays plain XHTTP on loopback.

If API calls fail, the script prints a manual fallback checklist. See references/manual-bootstrap.md for UI-only steps. Do not manually edit server config files; update the bundled scripts and rerun instead.

Inputs to step 5: panel URL, admin username and password, public domain, backend port, secret path.

Outputs from step 5: one VLESS inbound created, one client URL printed and ready to use.

Step 6: Add more clients (optional, repeat as needed)

To add another client to an existing inbound without changing nginx or the path:

python3 scripts/add-inbound-client.py \
  --panel-url http://127.0.0.1:12053 \
  --username admin \
  --password 'panel-secret' \
  --inbound-id 1

This script:

• logs in to the 3X-UI panel
• loads the specified inbound (or auto-selects if only one inbound exists)
• appends one new VLESS client to the existing inbound
• reuses the existing domain, path, and transport
• prints the new vless:// client URL

Do not create a second inbound with duplicate settings; always append to the existing one.

Inputs to step 6: panel URL, admin username and password, inbound ID (optional if only one inbound exists).

Outputs from step 6: one new client appended to the inbound, new client URL printed.

Step 7: Run updates (optional, repeat periodically)

Keep the host and container stack current with conservative updates:

./scripts/update-stack.sh \
  --host root@example-vps \
  --ssh-password 'host-password'

This script:

• runs apt update && apt upgrade (not full-upgrade)
• pulls the latest 3X-UI and nginx images
• runs docker compose up -d to restart containers
• reapplies panel loopback bind on 127.0.0.1:2053
• reapplies subscription server loopback bind on 127.0.0.1:2096
• reapplies UFW allow rules for SSH, HTTP, HTTPS

Do not switch to full-upgrade unless the user explicitly requests it. Reruns are safe.

Inputs to step 7: host, SSH password.

Outputs from step 7: updated OS, pulled container images, stack restarted, loopback binds and firewall rules reapplied.

decision points

• If SSH uses key auth, not password: Omit the --ssh-password parameter. The script falls back to your local SSH agent or key in ~/.ssh/id_rsa.

• If SSH auth is password-only: Pass the plain-text password via --ssh-password 'password'. This is inherently insecure; prefer key auth where possible.

• If the VPS already has a certificate for the same domain: The bootstrap script detects this and reuses the certificate instead of failing on ACME "Domains not changed" errors. No action needed.

• If bootstrap fails because the host is in an unexpected state (e.g., Docker already installed, nginx already running, stale 3X-UI containers): Stop, examine the error output, patch the relevant script locally, and rerun. Do not manually edit /opt/3x-ui/docker-compose.yml, nginx config, or 3X-UI settings over SSH.

• If the panel tunnel fails with immediate SSH disconnects: Stop parallel SSH sessions to the same host, wait 10 seconds, and retry a single tunnel connection. If the problem persists, check whether the VPS is rate-limiting or the panel is hung (run ssh <target> 'docker compose -f /opt/3x-ui/docker-compose.yml ps' to verify the panel container is running).

• If panel API calls fail during inbound bootstrap or client add: Stop guessing at panel API behavior. Print the manual fallback checklist from the script output and follow the UI-only steps in references/manual-bootstrap.md. Update the bundled scripts to match any recent 3X-UI API changes and rerun.

• If you need a public panel (not recommended): Treat this as a separate hardening decision outside this skill. The scripts intentionally bind the panel to loopback to protect it from direct internet access.

• If apt upgrade or docker compose up -d fails during update: The update-stack.sh script stops cleanly and reports the error. Inspect the host, fix the root cause (disk space, broken packages, container image unavailable), and rerun the update script.

• If the operator provides neither SSH key auth nor password: The skill cannot proceed. Request either a private key file or confirmation of the plain-text password before invoking scripts.

output contract

Success is defined by the following state on the target VPS:

• Docker Compose stack running under /opt/3x-ui/:

  • 3X-UI panel container listening on 127.0.0.1:2053
  • 3X-UI subscription server listening on 127.0.0.1:2096
  • Xray backend inbound listening on 127.0.0.1:1234 (or the configured backend port)

• nginx listening on public 0.0.0.0:80 and 0.0.0.0:443:

  • HTTP traffic on port 80 redirects to HTTPS
  • HTTPS terminates TLS for the public domain
  • unmatched HTTPS traffic returns HTTP 401 (not 444)
  • requests to the configured secret path are proxied via gRPC to the backend inbound

• ACME certificate issued and installed:

  • certificate stored in /opt/3x-ui/3x-ui-data/cert/
  • nginx config references the certificate path
  • certificate is valid for the public domain

• UFW firewall active and correctly configured:

  • SSH (port 22) allowed from all sources
  • HTTP (port 80) allowed from all sources
  • HTTPS (port 443) allowed from all sources
  • all other inbound traffic denied

• Bootstrap parameters persisted in /opt/3x-ui/bootstrap.env:

  • contains domain, panel admin credentials, ACME email, backend port, and secret path

• At least one VLESS inbound created in 3X-UI:

  • transport configured as XHTTP on the backend
  • bound to the configured backend port on loopback
  • at least one VLESS client enrolled in the inbound

• SSH panel tunnel established (when running open-panel-tunnel.sh):

  • local port forward from operator workstation to 127.0.0.1:12053 (or configured local port) to remote 127.0.0.1:2053
  • tunnel remains open until interrupted

outcome signal

The operator knows the skill worked when:

1. Fresh deploy: The bootstrap script completes without errors, and verification commands confirm nginx on public 443, panel on loopback 2053, Xray backend on loopback 1234, and UFW allowing only SSH/HTTP/HTTPS.

2. Panel access: The SSH tunnel opens without disconnecting, and http://127.0.0.1:12053 displays the 3X-UI login page. Log in with the provided admin credentials.

3. Inbound bootstrap: The bootstrap-inbound.py script prints a working vless:// client URL that clients can immediately import into their proxy software. The URL contains the public domain, the secret path, and XHTTP transport.

4. Add client: The add-inbound-client.py script prints a new vless:// client URL for the same inbound, with the same domain and path. The existing client URLs remain valid.

5. Updates: The update-stack.sh script completes without errors, and rerunning verification commands shows the same listeners active and UFW rules intact.

6. End-to-end test: A client connecting to the vless:// URL should establish a VLESS over XHTTP tunnel through nginx on the public 443 port, authenticate, and obtain IP connectivity through the proxy.

---

Script inventory

• scripts/bootstrap-host.sh: install Docker, nginx, ACME, Docker Compose stack, panel loopback binding, subscription loopback binding, nginx TLS config, and UFW rules
• scripts/ssh-with-password.sh: internal wrapper for ssh with optional plain-text password auth support
• scripts/open-panel-tunnel.sh: establish an SSH local port forward to the loopback-bound panel
• scripts/bootstrap-inbound.py: log in to 3X-UI panel, create one VLESS inbound, enroll one client, print client URL
• scripts/add-inbound-client.py: log in to 3X-UI panel, load an existing inbound, append one VLESS client, print client URL
• scripts/update-stack.sh: run apt update && apt upgrade, pull latest container images, restart Docker Compose stack, reapply loopback binds and firewall rules

References

• references/architecture.md: deploy topology, nginx routing behavior, XHTTP transport rationale
• references/manual-bootstrap.md: panel UI fallback steps and field mapping for inbound and client creation

---

Original author: olegtsvetkov