Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Gaurav-Gosain/tuios/llms.txt

Use this file to discover all available pages before exploring further.

​
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

# 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

which tuios
# Should show the installation path
4

Optional: Set Up Shell Completions

Enable tab completion for your shell:
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 BinaryThe 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 ServerA 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

Solution: Set the COLORTERM environment variable:
export COLORTERM=truecolor
Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.
Solution: Either install a Nerd Font or run TUIOS with ASCII-only mode:
tuios --ascii-only
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.
Solution: Make the binary executable:
chmod +x /path/to/tuios
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: 
brew upgrade tuios
brew upgrade tuios-web

Build docs developers (and LLMs) love

Get started for freeTalk to us