Installation

Install TUIOS on macOS, Linux, Windows, or FreeBSD using package managers, pre-built binaries, Docker, or build from source

System Requirements

Before installing TUIOS, ensure your system meets these requirements:

Terminal

A modern terminal emulator with true color support (most terminals since 2018)

Go Version

Go 1.24+ (only required if building from source)

Recommended terminals: Kitty, Alacritty, iTerm2, Windows Terminal, Wezterm, or any terminal with true color support. Set COLORTERM=truecolor if colors aren’t displaying correctly.

Installation Methods

1. Choose Your Installation Method

   Select the installation method that works best for your system and workflow. Package managers are recommended for easy updates.

2. Install TUIOS

   Package Managers (Recommended)

   Homebrew (macOS/Linux)

   # Install TUIOS terminal window manager
   brew install tuios
   
   # Install tuios-web (separate binary for web terminal server)
   brew install tuios-web
   

   Pre-built Binaries

   Download pre-built binaries for your platform from GitHub Releases.

   Available for:

   • Linux (amd64, arm64, armv6, armv7)
   • macOS (amd64, arm64)
   • Windows (amd64, arm64)
   • FreeBSD (amd64, arm64)

   Each release includes both tuios and tuios-web binaries.

   # Example: Install on Linux (replace with latest version)
   wget https://github.com/Gaurav-Gosain/tuios/releases/download/v0.3.4/tuios_Linux_x86_64.tar.gz
   tar -xzf tuios_Linux_x86_64.tar.gz
   sudo mv tuios /usr/local/bin/
   sudo chmod +x /usr/local/bin/tuios
   

   Docker

   Run TUIOS in a container without installation:

   docker run -it --rm ghcr.io/gaurav-gosain/tuios:latest
   

   Docker mode runs TUIOS in an isolated container. Sessions won’t persist after the container exits unless you mount volumes.

   Build from Source

   For the latest development version or custom builds:

   # Clone the repository
   git clone https://github.com/Gaurav-Gosain/tuios.git
   cd tuios
   
   # Build TUIOS main binary
   go build -o tuios ./cmd/tuios
   
   # Build tuios-web binary
   go build -o tuios-web ./cmd/tuios-web
   
   # Run the binary
   ./tuios
   
   # Or install to $GOPATH/bin
   go install ./cmd/tuios
   go install ./cmd/tuios-web
   

   Use Nix for reproducible development environments: nix develop to enter a shell with all dependencies, or nix build to build the package.

3. Verify Installation

   Confirm TUIOS is installed correctly:

   # Check version
   tuios --version
   
   # Should output something like:
   # tuios version v0.3.4
   

   Verify tuios

   which tuios
   # Should show the installation path
   
4. Optional: Set Up Shell Completions

   Enable tab completion for your shell:

   Bash

   tuios completion bash > /etc/bash_completion.d/tuios
   # Or for user-only installation:
   tuios completion bash > ~/.local/share/bash-completion/completions/tuios
   
5. Optional: Configure Terminal

   For the best experience, ensure your terminal supports:

   • True Color: Set export COLORTERM=truecolor in your shell profile
   • Nerd Fonts (optional): Install a Nerd Font for icons (or use --ascii-only flag)
   • Mouse Support: Should work by default in most modern terminals

   # Add to ~/.bashrc, ~/.zshrc, or equivalent
   export COLORTERM=truecolor
   

Understanding the Binaries

TUIOS provides two separate binaries:

tuios

Main Binary

The core terminal window manager. This is what you’ll use for local terminal sessions, daemon mode, SSH server, and tape scripting.

Use this for: Daily terminal work, local sessions, automation

tuios-web

Web Terminal Server

A separate binary that serves TUIOS through a web browser. Provides WebGL rendering, WebTransport/WebSocket support, and bundled Nerd Fonts.

Use this for: Remote access via browser, demos, accessing TUIOS from devices without SSH

The two binaries are separate for security isolation. You can install just tuios if you don’t need web terminal functionality.

Installation Verification

Run a quick test to ensure everything works:

# Launch TUIOS
tuios

# You should see the TUIOS interface with:
# - A dockbar at the bottom showing "Window 1"
# - A welcome message or your default shell
# - Status indicators in the corners

Test basic operations:

1. Press n to create a new window (should see “Window 2”)
2. Press Tab to switch between windows
3. Press ? to see the help overlay with keybindings
4. Press q to quit TUIOS

If colors aren’t displaying correctly, try setting export COLORTERM=truecolor in your shell profile and restart your terminal.

Troubleshooting

Colors not displaying correctly

Solution: Set the COLORTERM environment variable:

export COLORTERM=truecolor

Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

Icons showing as boxes or question marks

Solution: Either install a Nerd Font or run TUIOS with ASCII-only mode:

tuios --ascii-only

Go install command not found

Solution: Ensure $GOPATH/bin is in your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Add this to your shell profile to make it permanent.

Permission denied when running binary

Solution: Make the binary executable:

chmod +x /path/to/tuios

Homebrew installation fails

Solution: Update Homebrew and try again:

brew update
brew upgrade
brew install tuios

Next Steps

Now that TUIOS is installed, continue to the Quick Start guide to learn the essential keybindings and workflows:

Quick Start Guide

Get up and running with TUIOS in 5 minutes

Additional Resources

• Configuration: Learn how to customize keybindings and settings
• CLI Reference: Complete command-line options and flags
• Keybindings: Full keyboard shortcut reference
• Architecture: Technical architecture and design details

Updates

Keep TUIOS up to date:

Homebrew

brew upgrade tuios
brew upgrade tuios-web