Get Started — Suwu Docs

Install

One command downloads the latest release binary to ~/.local/bin/suwu and launches onboarding:

curl -fsSL https://raw.githubusercontent.com/liyu1981/suwu/refs/heads/master/install.sh | sh

That's it. The installer handles everything — binary download, PATH setup, and first-run configuration.

Requirements

Suwu runs on Linux (amd64, arm64). You need a POSIX shell for the installer. No other dependencies are required — Node.js, Go, and build tools are only needed if you want to build from source.

First Run

After installation, suwu launches automatically. On the first run, the onboarding wizard walks you through setup:

1. Shell Detection

Suwu detects your default login shell (bash, zsh, fish, etc.) and verifies it works. If you want to use a different shell, set the SHELL environment variable before starting.

2. Dev Tools Check

The wizard checks for common development tools (Go, Node.js, Git, etc.) and reports what's installed. Missing tools are optional — Suwu works without them.

3. Password Setup

Onboarding requires a web access password. Choose one interactively or let Suwu generate a secure one; the final summary prints it highlighted for you to save:

suwu onboard

4. HTTPS

HTTPS is the default server mode. Onboarding generates self-signed certificates automatically; use SERVER_MODE=http only when plain HTTP is intentionally required.

suwu gencerts

5. Your First Terminal

Onboarding finishes by opening a terminal tile. You should see a shell prompt — Suwu is running.

Access the Web UI

Open your browser and go to:

https://127.0.0.1:8181

You'll see the Suwu interface with your terminal tile. Enter the password configured during onboarding when prompted.

Tip

Bookmark this URL. If you changed the port, use that instead (check the server output for the actual URL).

From Another Device

To access Suwu from your phone, tablet, or another computer on the same network:

Find your machine's LAN IP (e.g., 192.168.1.42).
Make sure Suwu is binding to all interfaces: HOST=0.0.0.0 suwu serve.
Open http://192.168.1.42:8080 on the other device.

For internet access behind a reverse proxy, see Security & Access.

Running Onboarding Again

To re-run the onboarding process at any time — for example after system updates or when adding new tools:

suwu onboard

Each step shows a ✓ or ✗ status. You can skip any step and configure it later.

What's Next

Tiling Window Manager — learn to split, move, and arrange tiles.
Terminals — keyboard shortcuts, session persistence, agent integration.
Suwu CLI — suwu send, suwu forward, suwu open.
File Browser — navigate and manage files in a tile.

Keeping Suwu Updated

When a new version is released, update with:

suwu upgrade

This downloads the latest binary and restarts the server. See Upgrading for details.

Build from Source

If you want to build Suwu yourself instead of using the installer:

# Clone the repo
git clone https://github.com/liyu1981/suwu.git
cd suwu

# Install frontend dependencies and build
pnpm install && pnpm --dir frontend install
pnpm build:web

# Build the Go binary
pnpm build

# Run
./suwu serve

You'll need Go 1.27.1+, Node.js, and pnpm. See the README for full details.