Getting Started

This guide covers installation, first run, and basic usage of NØXTERM.

---

Prerequisites

Component	Minimum	Recommended	Notes
Docker	20.10+	24.0+	Auto-installed if missing
Rust	1.70+	Latest stable	For backend compilation
Node.js	18.0+	20.0+ LTS	For frontend and privacy mode

NØXTERM can automatically install Docker and Node.js on most platforms. See Auto-Setup for details.

---

Installation

Clone and Build

# Clone the repository
git clone https://github.com/NON-OS/noxterm.git
cd noxterm

# Build the backend
cd nox-backend
cargo build --release

# Build the frontend
cd ../frontend
npm install
npm run build

---

Start the Services

Terminal 1: Backend

cd nox-backend
cargo run --release

The backend starts on http://0.0.0.0:3001 by default.

Terminal 2: Frontend (Development)

cd frontend
npm run dev

The frontend development server starts on http://localhost:5173.

Verify Installation

# Check backend health
curl http://localhost:3001/health

# Expected response:
# {"status":"healthy","timestamp":"..."}

Open http://localhost:5173 in your browser to access the terminal interface.

---

First Session

Creating a Terminal

1. Enter a username (alphanumeric, underscores, hyphens allowed)

2. Select a container image from the dropdown:

ArchLinux, Ubuntu 24.04-22.04, Alpine, Debian.

Click "Create Terminal Session"

The container spawns within seconds. You'll see a bash prompt ready for input.

Basic Commands

# Verify your environment
uname -a
cat /etc/os-release

# Check available resources
free -h
df -h

# Install packages (will not persist after session)
apt update && apt install -y curl htop vim

# Test network connectivity
curl https://httpbin.org/ip

# Run interactive applications
htop
vim test.txt

---

Terminal Features

Copy/Paste

• Copy: Select text with mouse, use Ctrl+C (or Cmd+C on macOS)

• Paste: Ctrl+V (or Cmd+V on macOS)

Terminal Resize

• The terminal automatically resizes when you resize your browser window

• Interactive applications (vim, htop) respond to resize events

Interactive Editors

• nano filename - Simple text editor, Ctrl+X to exit

• vim filename - Modal editor, :wq to save and quit

---

Session Management

Multiple Sessions

Each user can run up to 3 concurrent containers. Create additional sessions by opening new browser tabs and creating terminals with the same username.

Session Persistence

If you close the browser tab or lose connection:

• The container continues running for a grace period (default: 5 minutes)

• Reopen the session URL or create a new session with the same ID to reattach

• After the grace period, the container is automatically destroyed

Ending a Session

Sessions end when:

• You explicitly terminate them via the UI

• The grace period expires after disconnection

• The backend process restarts

• Resource limits are exceeded

---

Auto-Setup

NØXTERM can automatically install missing dependencies.

Docker Auto-Installation

macOS

• Installs Colima (lightweight Docker alternative) via Homebrew

• Falls back to Docker Desktop installation prompt

Linux

• Uses official Docker installation script

• Supports apt, dnf, yum, and pacman package managers

Windows

• Prompts for manual installation (cannot auto-install GUI applications)

• Supports Docker Desktop or WSL2 with Docker

Node.js Auto-Installation

Required only for privacy mode. When you enable privacy:

macOS

• Homebrew: brew install node

• Falls back to nvm if Homebrew unavailable

Linux

• NodeSource repository for apt-based systems

• Package manager installation for others

Windows

• winget, Chocolatey, or Scoop

---

Development Mode

For active development with hot reload:

Backend

cd nox-backend
RUST_LOG=noxterm=debug cargo run

Frontend

cd frontend
npm run dev

The frontend dev server proxies API requests to the backend automatically.

---

Production Deployment

Build Optimized Binaries

# Backend (release build with optimizations)
cd nox-backend
cargo build --release
# Binary: target/release/noxterm-backend

# Frontend (production build)
cd frontend
npm run build
# Static files: dist/

Docker Deployment

# Build frontend container
docker build -f frontend/Dockerfile -t noxterm-frontend:latest .

# Run with custom configuration
DATABASE_URL=postgresql://user:pass@localhost/noxterm \
SERVER_PORT=3001 \
ENVIRONMENT=production \
./target/release/noxterm-backend

Reverse Proxy Configuration

For production, run behind nginx or Caddy for HTTPS termination:

nginx example

server {
    listen 443 ssl http2;
    server_name terminal.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Frontend static files
    location / {
        root /var/www/noxterm/dist;
        try_files $uri $uri/ /index.html;
    }

    # Backend API
    location /api {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # WebSocket endpoints
    location ~ ^/(ws|pty)/ {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }

    # Health checks
    location /health {
        proxy_pass http://127.0.0.1:3001;
    }
}

Troubleshooting

Docker Not Found

Error: Docker socket not found

Solution: Install Docker and ensure the daemon is running.

• macOS: Install Docker Desktop or Colima

• Linux: sudo systemctl start docker

• Windows: Start Docker Desktop

Container Creation Fails

Error: Failed to create container

Possible causes:

• Docker daemon not running

• Image not available (will auto-pull on first use)

• Resource limits exceeded on host

• Disk space full

WebSocket Connection Failed

Error: WebSocket connection failed

Check:

• Backend is running on expected port

• No firewall blocking WebSocket connections

• Reverse proxy configured for WebSocket upgrade

Permission Denied

Error: Permission denied connecting to Docker socket

Solution: Add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in