Frequently Asked Questions

Common questions and answers about NioDE Server and the NioDE app.

Installation

How do I install nio-de?

Use npx @nio-labs/nio-de with Node.js, or use the native install script on Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/nio-labs/nio-de/main/install.sh | bash

This automatically detects your OS and architecture, downloads the prebuilt binary, verifies its SHA-256 checksum, and installs it to ~/.local/bin (or /usr/local/bin when run as root).

Do I need Rust or Node.js to run nio-de?

No Rust or Node.js is needed for the native server. Node.js is required for npx @nio-labs/nio-de and the npm installation of NioAI. NioAI (nio) also has a standalone native installer. The server installers automatically install it if it is missing.

What platforms are supported?

nio-de supports Linux (x86_64, aarch64), macOS (x86_64, aarch64), Windows (x86_64), and Android (Termux, aarch64). For Android, use AndroNix proot for better performance with Nio chat.

Can I install a specific version?

Yes. Set the VERSION environment variable before running the install script:

VERSION=0.2.2 bash install.sh

Re-running the same command upgrades you to the newest version by default.

Running

How do I start nio-de?

After installation, run:

nio-de

By default, it prints a fresh pairing code (XXXX-XXXX) plus a QR code, and listens for WebSocket connections on 0.0.0.0:1421.

What are the authentication modes?

There are three modes:

  • Pairing (default): Server prints a fresh XXXX-XXXX code + QR at startup. Ephemeral, never stored, rotated on restart.
  • Fixed token: Use --token <value> or NIO_DE_TOKEN=.... The same token works across restarts.
  • No auth: Accept unauthenticated connections. Loud warning. Development/CI only.

How do I use a fixed token instead of pairing?

nio-de --token "$(openssl rand -hex 24)"

Or set the environment variable:

NIO_DE_TOKEN=... nio-de

How do I bind to a different address and port?

NIO_DE_WS_ADDR=0.0.0.0:1421 nio-de

You can override the default 0.0.0.0:1421 with any host and port.

Connecting the NioDE App

How do I pair the NioDE app with the server?

  1. Start nio-de (keep the terminal visible)
  2. On first launch, the NioDE app shows the pairing screen automatically — enter the code printed on the server console.
  3. If the server is remote, also set the Server URL to ws://<host>:1421 or wss://...

The app sends the code as ?token=... on every connection.

What's the pairing code format?

The code is two groups of four uppercase letters or digits separated by dashes: XXXX-XXXX (e.g., WD5D-CGSP).

Can I use a QR code scanner?

The server prints a scannable ASCII QR code on startup. QR scanning is available now. Use the camera in the app to scan the QR code printed by the server.

What if the server and app are on different machines?

Enter the full Server URL in the app's Settings → Server field, e.g., ws://192.168.1.20:1421 (or wss://your-host:443 for internet access). Use wss:// outside a trusted LAN.

Security

Is pairing secure by default?

Yes. Pairing is on by default — anyone who can reach the port still needs the code that only ever exists on the server's console. Restarting the server rotates the code.

Should I use wss:// or ws:// outside my LAN?

Always use wss:// outside a trusted LAN. The token travels in the URL query string, which intermediaries can log — never reuse long-lived credentials here.

What about self-signed certificates?

Avoid them. Browsers and mobile WebViews refuse untrusted wss:// endpoints — use Caddy / Let's Encrypt / a tunnel provider instead.

When should I use --no-auth?

Only for localhost development or CI. Anyone who can reach the port can read, write, and delete files and run shells on the host.

Mobile App

Can I use the mobile app with a remote server?

Yes. Enter the Server URL and pairing code (or use the wss:// URL) in Settings → Server. All files, shells, and chat come from the server — no local folder mounting on mobile.

Production Deployment

Can I use GitHub Codespaces?

Yes. Run nio-de in a Codespace — it's free within your monthly quota, gives Nio a full Linux environment, and its port forwarding gives you a wss:// URL automatically.

What's the relationship between NioDE and nio-de?

NioDE is the frontend app. nio-de is the self-hosted backend (Rust binary) that provides PTY terminals, file operations, git, and Nio AI chat over WebSocket. This website documents the server and how to use it with the NioDE app.

Troubleshooting

The app won't connect to the server

  • Check the server is running and printing the pairing code
  • Ensure the Server URL and pairing code are correct
  • Verify ports 1421 (server) and 1420 (frontend) are open if running locally
  • For remote connections, use wss:// and ensure TLS is properly configured

How do I upgrade?

For the latest version:

curl -fsSL https://raw.githubusercontent.com/nio-labs/nio-de/main/install.sh | bash

For a specific version, set VERSION=0.5.2 before running. Restart the server after upgrading.