| name | 3x-ui-vps |
| description | Deploy and manage 3X-UI on a root-managed Ubuntu or Debian VPS using Docker Compose, nginx, ACME certificates, SSH panel tunneling, UFW hardening, and Xray VLESS over XHTTP behind nginx. Use when the user explicitly wants to install 3X-UI from scratch, lock the panel and subscription server to 127.0.0.1, open an SSH tunnel to the panel, create or repair a VLESS inbound behind nginx on public 443, add extra clients to an existing inbound, or run safe OS and container updates. |
| disable-model-invocation | true |
| metadata | {"openclaw":{"requires":{"bins":["bash","python3","ssh"]}}} |
3X-UI VPS
Deploy 3X-UI on a VPS with the panel and subscription server bound to loopback, ufw allowing only SSH/HTTP/HTTPS, nginx on public 80/443, and one VLESS + XHTTP transport routed through nginx.
This skill is manual-first because it mutates remote infrastructure. Invoke it only when the user explicitly asks to deploy, repair, harden, or update a VPS.
Hard rule
- All server-side configuration must be executed only through the bundled scripts in this skill.
- Do not create or edit remote configs manually over SSH, do not run ad-hoc heredocs on the server, and do not "quick-fix" nginx, Docker, ACME, or 3X-UI by hand.
- Read-only inspection commands are allowed for diagnosis.
- If a script fails because the host is in an unexpected state, stop changing the server, patch the relevant script locally in this skill, and rerun the script.
- The manual fallback in this skill is for the 3X-UI panel UI only. It is not permission to mutate server files manually.
Inputs
Collect these before doing any work:
ssh target for the VPS, preferably root@host- optional plain-text SSH password if the host is password-auth only
- public domain pointed at the VPS
- optional ACME email
- panel admin username and password
- optional local tunnel port
Assume Ubuntu or Debian with apt. Do not use this skill on other distributions without adapting the Docker repository setup first.
The operator workstation and the target VPS also need outbound internet access for Docker downloads, ACME issuance, and panel API calls.
Preflight
Before changing the host, confirm these assumptions:
- the domain already resolves to the VPS from the server side, not only from the operator workstation
- the operator knows whether SSH access is key-based or password-based
- if the host already has a certificate for the same domain, reruns must reuse it instead of treating
acme.sh "Domains not changed" as a hard failure
- if panel tunneling starts failing with immediate SSH disconnects after several quick attempts, stop parallel retries, wait briefly, and retry one connection at a time
Workflow
1. Fresh deploy
Use scripts/bootstrap-host.sh.
Example:
./scripts/bootstrap-host.sh \
--host root@example-vps \
--ssh-password 'host-password' \
--domain vpn.example.com \
--panel-username admin \
--panel-password 'panel-secret'
Default shape:
- 3X-UI runs via Docker Compose under
/opt/3x-ui
- Docker is installed on Ubuntu and Debian hosts through
get.docker.com
- container keeps
network_mode: host
- data lives under
3x-ui-data/db/
- certificates live under
3x-ui-data/cert/
- panel must bind to
127.0.0.1:<panel_port>
- subscription server must bind to
127.0.0.1:2096
- panel admin username and password must be applied during deploy
- the script must resolve the public domain on the server itself with
dig before ACME issuance
- nginx terminates TLS on public
443
- nginx returns
401 for unmatched traffic
- nginx proxies only the configured Xray secret path to the local backend port with
grpc_pass
ufw must allow only SSH, HTTP, and HTTPS from the internet
After deploy, verify:
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'
Read references/architecture.md if you need the full topology or nginx routing rationale.
2. Panel access
Use scripts/open-panel-tunnel.sh and keep the panel SSH-only.
Default tunnel:
./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.
If the tunnel fails with an immediate SSH disconnect, avoid parallel SSH sessions to the same host for a short period and retry the tunnel as a single connection after a brief pause.
Do not publish the panel in nginx. If the operator later wants a public panel, treat that as a separate hardening decision.
3. Quick inbound bootstrap
Use scripts/bootstrap-inbound.py against the tunneled panel URL.
Important detail:
- public client transport is
TLS because nginx terminates TLS on 443
- backend Xray inbound behind nginx stays plain
XHTTP on loopback
- the inbound path must match the nginx secret path
Preferred flow:
python3 scripts/bootstrap-inbound.py \
--panel-url http://127.0.0.1:12053 \
--username admin \
--password 'secret' \
--public-domain vpn.example.com \
--backend-port 1234 \
--path /xhttp-keep-this-secret
The script prefers API automation but always prints a manual fallback checklist. Use references/manual-bootstrap.md if API endpoints drift or the panel UI has changed.
That fallback is UI-only. If server-side behavior needs to change, update the bundled scripts first and rerun them.
4. Add another client to an existing inbound
Use scripts/add-inbound-client.py against the tunneled panel URL.
This workflow is for adding one more client to an already working inbound without changing nginx, ports, or the existing secret path.
Preferred flow:
python3 scripts/add-inbound-client.py \
--panel-url http://127.0.0.1:12053 \
--username admin \
--password 'secret' \
--inbound-id 1
Behavior:
- the script logs in to 3X-UI through the panel tunnel
- loads the existing inbound
- appends one more VLESS client to
settings.clients
- keeps the existing public domain and XHTTP path from that inbound
- updates the same inbound instead of creating a second parallel inbound
- prints a ready-to-import
vless:// client URL
If --inbound-id is omitted, the script may auto-select the inbound only when the panel has exactly one inbound. Otherwise require the operator to pass the inbound ID explicitly.
5. Updates
Use scripts/update-stack.sh.
The update workflow must stay conservative:
./scripts/update-stack.sh --host root@example-vps --ssh-password 'host-password'
This runs:
apt updateapt upgradedocker compose pulldocker compose up -d- reapply panel loopback bind
- reapply subscription loopback bind on
2096
- reapply
ufw rules for SSH, HTTP, and HTTPS only
Do not switch this skill to apt full-upgrade unless the user explicitly asks for it.
Fast troubleshooting
Use these checks before assuming the deploy is broken:
ssh <target> 'ss -ltnp | egrep ":2053 |:2096 |:1234 |:443 |:80 "'ssh <target> 'docker compose -f /opt/3x-ui/docker-compose.yml ps'ssh <target> 'curl -I http://127.0.0.1:2053/'ssh <target> 'cat /opt/3x-ui/bootstrap.env'- local tunnel check:
lsof -nP -iTCP:12053 -sTCP:LISTEN
Interpretation:
127.0.0.1:2053 and 127.0.0.1:2096 mean panel and sub server are correctly isolated127.0.0.1:1234 means the Xray backend inbound exists- public
0.0.0.0:80 and 0.0.0.0:443 should belong to nginx
curl -I http://127.0.0.1:2053/ returning 404 is acceptable and proves the panel is respondinghttps://<domain>/ returning 401 is the expected nginx default for unmatched traffic
Decision rules
- Prefer the bundled scripts over retyping long shell sessions.
- Treat the bundled scripts as the only writable interface to the server state.
- If deployment or update fails, fix the script or add a new script in this skill. Do not repair the server manually.
- If the operator provides a plain-text SSH password, pass it through to the bundled script with
--ssh-password instead of wrapping SSH manually.
- Keep Docker installation simple and consistent by using
curl -fsSL https://get.docker.com -o get-docker.sh followed by sh ./get-docker.sh.
- Resolve the public domain from the server itself with
dig, not from the operator workstation, before relying on DNS results.
- Keep the panel on
127.0.0.1; verify with ss -ltnp.
- Keep the subscription server on
127.0.0.1:2096; verify with ss -ltnp.
- Keep nginx responsible for public
80/443.
- Keep the Xray backend on a separate loopback port such as
127.0.0.1:1234.
- Reuse the exact same secret path in nginx and the inbound config.
- When the operator asks for another client, prefer adding it to the existing inbound instead of creating a second inbound with duplicate transport settings.
- Keep
nginx default responses normal HTTP 401, not 444, so browsers receive a valid error page.
- Keep
ufw active and restricted to SSH, HTTP, and HTTPS ingress only.
- On current 3X-UI images, prefer
/app/x-ui setting ...; the x-ui wrapper may not apply panel settings correctly inside the container.
- If this 3X-UI version exposes an extra subscription listener, set
subListen=127.0.0.1 and verify that 2096 is not public.
- If 3X-UI API calls fail, stop guessing and use the manual fallback.
Script inventory
References
