Tovanix
Tovanix

nexcore-x-ui Installation & Operations Tutorial (Xray Panel)

Step-by-step guide to Astrenix/nexcore-x-ui: one-click install script, Vue 3 + Go static binary, systemd hardening, /api/v1 REST API, CLI creds and fixes.

  • A static Go binary paired with a Vue 3 + Element Plus SPA and Xray-core, removing strict host GLIBC version coupling.
  • A structured /api/v1 REST API built for external controllers, scripts and multi-node orchestration.
  • Strict systemd hardening (such as ProtectSystem=strict and NoNewPrivileges=true), 0700 data directories, 0600 database permissions and SHA256-hashed API tokens.
  • VLESS with XTLS-Reality, TCP, WebSocket and gRPC transports for low overhead and stable connections.

Architecture and key features

Refactored from vaxilu/x-ui for modern cloud provisioning and production security, nexcore-x-ui includes:

  • A static Go binary paired with a Vue 3 + Element Plus SPA and Xray-core, removing strict host GLIBC version coupling.
  • A structured /api/v1 REST API built for external controllers, scripts and multi-node orchestration.
  • Strict systemd hardening (such as ProtectSystem=strict and NoNewPrivileges=true), 0700 data directories, 0600 database permissions and SHA256-hashed API tokens.
  • Isolated install paths, systemd unit name and CLI binary (nexcore-x-ui) that do not collide with upstream x-ui.

System requirements

  • Operating system — Modern 64-bit Linux with systemd (clean Ubuntu 22.04 / 24.04 LTS or Debian 12 recommended).
  • Privileges — Root access is required to register the systemd unit, configure ports and secure the data directory.
  • Networking — Public IP with outbound access to GitHub Releases for downloading binaries, plus firewall rules allowing the panel and protocol ports.
  • Recommended servers — Pairs cleanly with Tovanix Native IP VPS, Dual-ISP VPS, Residential IP VPS or dedicated physical servers.

One-click installation & automated provisioning

Sign in to your server over SSH as root and run the official install script to fetch the static binary, register the service and generate random credentials:

bash <(curl -fsSL https://raw.githubusercontent.com/Astrenix/nexcore-x-ui/main/install.sh)

For cloud-init or controller-driven fleet provisioning, pass secure entry and webhook callback environment variables before invoking the installer:

REPORT_URL=https://your-controller.example/callback \
REPORT_KEY=your_secret \
SECURE_ENTRY=1 \
bash <(curl -fsSL https://raw.githubusercontent.com/Astrenix/nexcore-x-ui/main/install.sh)

Starting with v2.1.3, initial plaintext credentials are no longer written to install-info.txt on disk; they appear only in the terminal banner and systemd journal.

Retrieving initial login credentials

If you closed the terminal after installation, retrieve the bootstrap banner via the CLI or query the systemd journal directly:

nexcore-x-ui creds
journalctl -u nexcore-x-ui --no-pager --since "1 day ago"

After your first sign-in, change the generated password via the panel or nexcore-x-ui passwd and restrict access to the panel port in your firewall.

nexcore-x-ui CLI quick reference

Installation registers the global nexcore-x-ui command so service control, logs, password resets, updates and removal stay simple:

  • nexcore-x-ui — Launch the interactive terminal menu for common management actions.
  • nexcore-x-ui start | stop | restart | status — Start, stop, restart or inspect the status of the panel service.
  • nexcore-x-ui creds / info — Display the panel port, entry path and initial bootstrap credentials.
  • nexcore-x-ui reset — Regenerate a fresh random admin username, password and panel port.
  • nexcore-x-ui passwd <user> <new_password> — Manually set a new login password for the given admin username.
  • nexcore-x-ui log / log-tail — Print the latest 200 log lines or stream live panel logs.
  • nexcore-x-ui update — Upgrade smoothly to the latest GitHub Releases build and restart the service.
  • nexcore-x-ui uninstall — Remove binaries, systemd service files and the data directory (back up configs first).

Supported protocols and transports

Built directly on Xray-core, the panel supports per-user credentials, traffic quotas and expiry rules across:

  • VLESS with XTLS-Reality, TCP, WebSocket and gRPC transports for low overhead and stable connections.
  • VMess and Trojan for legacy client compatibility and TLS domain setups.
  • Shadowsocks and Shadowsocks-2022 for lightweight clients and fast relay links.
  • SOCKS, HTTP and Dokodemo-door for application proxies, port forwarding and multi-hop chaining.

After testing your inbound, run the exit IP through our free IP Quality Check to verify native and carrier ISP records.

Troubleshooting

  • Panel login page does not load in browser — The random panel port is blocked by the firewall or security group, or the secure entry path was omitted. — Run nexcore-x-ui status and nexcore-x-ui info to verify the port and path, then allow that TCP port in the console firewall.
  • Lost the initial random password — Versions v2.1.3 and newer do not leave plaintext credentials on disk. — Run nexcore-x-ui creds to read the journal banner, or reset it with nexcore-x-ui passwd <user> <new_password>.
  • Inbound is active but clients cannot connect — The protocol port is closed, the Reality handshake target fails, or server clock skew is too large. — Verify TCP / UDP firewall rules, sync NTP time on the server and inspect live Xray errors via nexcore-x-ui log-tail.
  • In-panel upgrade did not take effect — Download from GitHub Releases timed out or an older process remained active. — Run nexcore-x-ui update over SSH to watch the full log output, then confirm with nexcore-x-ui status.

Frequently Asked Questions

Can nexcore-x-ui coexist with upstream vaxilu/x-ui on one server?

Yes. Its binaries, data directory, systemd unit and CLI name are completely separate, so both can run side by side as long as ports do not overlap.

Does upgrading nexcore-x-ui erase existing inbounds and users?

No. In-panel updates and nexcore-x-ui update replace only the binaries while preserving your SQLite database and configurations.

How do I automate node management with /api/v1?

Create an API Token inside panel settings (stored server-side as a SHA256 hash), then call standard REST endpoints to manage inbounds, users and traffic stats.

Related pages: nexcore-s-ui Installation & Configuration Tutorial (sing-box Panel) · Self-Hosted Node Panel Guide: nexcore-x-ui, nexcore-s-ui & Dedicated Proxy · Private network deployment solution · VPS with native and residential IPs

Loading…