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.

This guide covers building TUIOS from source, including both the main tuios binary and the tuios-web web terminal server.

​
Prerequisites

​
Required

  • Go 1.25+ - TUIOS uses Go 1.25.0 or later
  • Git - For cloning the repository
  • A terminal with true color support - Most modern terminals work

​
Optional

  • Docker - For containerized builds
  • Nix - For Nix-based development

​
Clone the Repository

Clone the TUIOS repository from GitHub: 
git clone https://github.com/gaurav-gosain/tuios.git
cd tuios

​
Building TUIOS

​
Build the Main Binary

Build the tuios terminal window manager: 
go build -o tuios ./cmd/tuios
The binary will be created in the current directory. Run it: 
./tuios

​
Build tuios-web

Build the tuios-web web terminal server (separate binary for security isolation): 
go build -o tuios-web ./cmd/tuios-web
Run the web server: 
./tuios-web
# Opens on http://localhost:7681

​
Build Both Binaries

Build both binaries at once: 
go build -o tuios ./cmd/tuios
go build -o tuios-web ./cmd/tuios-web

​
Install to GOPATH

Install binaries to $GOPATH/bin (or $GOBIN): 
# Install tuios
go install ./cmd/tuios

# Install tuios-web
go install ./cmd/tuios-web
Ensure $GOPATH/bin is in your PATH to run the commands directly: 
tuios
tuios-web

​
Development Builds

​
Run Without Building

Run directly with go run: 
# Run tuios
go run ./cmd/tuios

# Run tuios-web
go run ./cmd/tuios-web

# Run with debug logging
go run ./cmd/tuios --debug
go run ./cmd/tuios-web --debug

​
Build with Debug Symbols

Build with full debug information: 
go build -gcflags="all=-N -l" -o tuios ./cmd/tuios

​
Build with Race Detection

Build with race detector (slower but catches race conditions): 
go build -race -o tuios ./cmd/tuios
Race detection significantly impacts performance. Only use for testing, not production.

​
Development with Nix

TUIOS includes Nix flake support for reproducible builds.

​
Enter Development Shell

The development shell includes Go, dependencies, and development tools: 
nix develop
Inside the shell, build and run normally: 
go build -o tuios ./cmd/tuios
./tuios

​
Build with Nix

Build the package using Nix: 
nix build
The built binary is in ./result/bin/tuios.

​
Run Directly

Run TUIOS without building: 
nix run

​
Run from GitHub

Run the latest version directly from GitHub: 
nix run github:Gaurav-Gosain/tuios#tuios

​
Docker Build

​
Build Docker Image

Build the TUIOS Docker image: 
docker build -t tuios .

​
Run in Container

Run TUIOS in an interactive container: 
docker run -it --rm tuios

​
Use Official Image

Use the pre-built image from GitHub Container Registry: 
docker run -it --rm ghcr.io/gaurav-gosain/tuios:latest

​
Build Options and Flags

​
Optimization Levels

# Default optimization
go build -o tuios ./cmd/tuios

# Disable optimizations (for debugging)
go build -gcflags="-N -l" -o tuios ./cmd/tuios

# Aggressive optimization (smaller binary)
go build -ldflags="-s -w" -o tuios ./cmd/tuios

​
Static Linking

Build a fully static binary (useful for containers): 
CGO_ENABLED=0 go build -o tuios ./cmd/tuios

​
Cross-Compilation

Build for different platforms: 
# Linux (amd64)
GOOS=linux GOARCH=amd64 go build -o tuios-linux-amd64 ./cmd/tuios

# macOS (arm64)
GOOS=darwin GOARCH=arm64 go build -o tuios-darwin-arm64 ./cmd/tuios

# Windows
GOOS=windows GOARCH=amd64 go build -o tuios.exe ./cmd/tuios

# FreeBSD
GOOS=freebsd GOARCH=amd64 go build -o tuios-freebsd ./cmd/tuios

​
Dependencies

​
Install Dependencies

Go modules handle dependencies automatically. Download all dependencies: 
go mod download

​
Update Dependencies

Update all dependencies to latest versions: 
go get -u ./...
go mod tidy

​
Vendor Dependencies

Copy dependencies into vendor/ directory: 
go mod vendor
Build using vendored dependencies: 
go build -mod=vendor -o tuios ./cmd/tuios

​
Key Dependencies

TUIOS is built on the Charm stack:
As of December 2025, Charm packages migrated from github.com/charmbracelet/* to charm.land/* module paths.

​
Build Troubleshooting

​
Go Version Too Old

If you see version errors: 
go version
# Should be 1.25.0 or later
Install the latest Go from go.dev/dl.

​
Missing Dependencies

If imports fail, download dependencies: 
go mod download
go mod tidy

​
Build Cache Issues

Clear the build cache if you encounter strange errors: 
go clean -cache -modcache
go build -o tuios ./cmd/tuios

​
Platform-Specific Issues

Linux: Ensure you have basic build tools: 
sudo apt-get install build-essential  # Debian/Ubuntu
sudo yum groupinstall "Development Tools"  # RHEL/CentOS
macOS: Install Xcode Command Line Tools: 
xcode-select --install
Windows: Use Git Bash or WSL for the best experience.

​
Verifying the Build

Check that the binary works: 
# Show version
./tuios version

# Show help
./tuios --help

# Run TUIOS
./tuios

​
Next Steps

After building TUIOS:

Build docs developers (and LLMs) love

Get started for freeTalk to us