@devboxer/terminal-server

Standalone CLI terminal server for iframe embedding. Serves a full-bleed terminal powered by ghostty-web.

Quick Start

npx @devboxer/terminal-server

This starts a local web server with a fully functional terminal connected to your shell. Works on Linux and macOS (Windows support via WSL).

Features

• Full-bleed terminal designed for iframe embedding (100vw × 100vh)
• WebSocket PTY with auto-reconnect
• Configurable shell, port, and working directory
• Session limits via environment variable
• Graceful shutdown (SIGTERM/SIGINT)

Usage

# Default (port 8080, binds to 0.0.0.0)
devboxer-terminal

# Custom port and host
devboxer-terminal --port 3000 --host 127.0.0.1

# Custom shell and working directory
devboxer-terminal --shell /bin/zsh --cwd /home/user/project

# Disable welcome banner
devboxer-terminal --no-welcome

# Limit concurrent sessions
MAX_SESSIONS=10 devboxer-terminal

CLI Options

| Option | Short | Default | Description | |--------|-------|---------|-------------| | --port | -p | 8080 | HTTP/WebSocket port | | --host | -H | 0.0.0.0 | Bind address | | --ws-path | -w | / | WebSocket path | | --shell | -s | $SHELL or /bin/bash | Shell executable | | --cwd | -c | $HOME | Working directory | | --restrict-origin | -o | | Restrict iframe embedding to origin (repeatable) | | --no-welcome | | false | Disable welcome banner | | --help | | | Show usage | | --version | | | Show version |

Environment Variables

| Variable | Description | |----------|-------------| | MAX_SESSIONS | Maximum concurrent sessions (default: unlimited) |

Iframe Embedding

The terminal is designed for iframe embedding with a full-bleed layout:

<iframe
  src="http://localhost:8080"
  style="width: 100%; height: 500px; border: none;"
></iframe>

Deployment Examples

Docker

FROM node:22-slim

RUN npm install -g @devboxer/terminal-server

EXPOSE 8080
CMD ["devboxer-terminal", "--host", "0.0.0.0"]

docker build -t terminal-server .
docker run -p 8080:8080 terminal-server

systemd

[Unit]
Description=Devboxer Terminal Server
After=network.target

[Service]
Type=simple
User=www-data
ExecStart=/usr/bin/npx @devboxer/terminal-server --port 8080
Restart=on-failure
Environment=MAX_SESSIONS=50

[Install]
WantedBy=multi-user.target

Reverse Proxy (nginx)

server {
    listen 80;
    server_name terminal.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Security Warning

⚠️ This server provides full shell access.

• Only expose to trusted networks
• Consider using --host 127.0.0.1 for local-only access
• Use MAX_SESSIONS to limit resource usage
• Place behind authentication proxy in production