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`

Enter a username (alphanumeric, underscores, hyphens allowed)
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

PreviousNØXTERM Overview

Last updated 4 days ago

Was this helpful?