Make the remote shell enjoyable in agentic AI time.
Your real shell, in a browser tab. Suwu gives agents and humans alike a tiling terminal that keeps running when you don't — refresh, disconnect, come back tomorrow, pick up where you left off.
Short captures of Suwu in daily use. Click a preview to watch the full clip on r/suwu.
![]() |
![]() |
| Eye candy & themes | Built-in git graph |
![]() |
![]() |
| REST helper | Database browser |
![]() |
![]() |
| Agent code review | X11 app forwarding |
![]() |
![]() |
| Daily remote workflow | Intro to Suwu |
-
A tile-based window manager, by keyboard or mouse — Split, focus, drag tiles into place, and swap them with fast key bindings or a click and drag — whichever fits the moment. Your sessions live in the layout: refresh the page, drop the connection, even restart the server, and every tile comes back exactly as you left it.
-
Full-featured terminals, perfect for agents — Real shells with selection, copy/paste, scrollback, and notifications — comfortable for you, and a solid target for agent orchestrators like
opencode,pi, andherdrthat drive many terminals at once. -
Convenient apps for everyday dev work — A file browser with download, a file viewer with auto-refresh, a TCP/UDP port forwarder, a database browser for SQLite, MySQL, and PostgreSQL, a side-by-side SFTP client for moving files to a remote machine, and a Postman-style REST helper that reaches
localhostand your LAN from the server side — the small tools you'd otherwise reach for a second terminal or a GUI client, right in the grid next to your shells. -
From terminal to web, with suwu commands —
suwu sendposts a notification to your screen from any script — pipe stdin in.suwu forwardopens a port-forwarding tile,suwu open,suwu code, andsuwu diffresolve files and actions on the remote machine. Long builds finish? You'll know.suwu static-serve <dir>previews a folder of web assets in a sandboxed browser tile at/staticserve/<id>/. -
Reachable, but only by you — Access works out of the box on localhost, your LAN, or over the internet behind a reverse proxy — with password authentication, per-run tokens, and one-command HTTPS.
-
Yours to tune — Pick your font family and size, theme the colors, dial in a glassy background alpha, and dock the header to any edge. Choose a full-viewport background — an ambient blob, a looping video clip, a 2D live wallpaper downloaded from a provider like MoeWalls, or a WebGPU shader scene — and drop your own into the data directory. The interface speaks English and Chinese out of the box.
-
Install once, stay current — Onboarding sets up your dev environment step by step, and
suwu upgradekeeps the binary fresh. No config files to babysit. -
Build output lands on your laptop — Folder Sync mirrors a folder on the server into a folder on your own computer, one way and re-checked every few seconds, straight from the browser.
-
Your own apps, in a sandbox — An extension is a small JavaScript program that returns an HTML page. It runs in a QuickJS isolate, in its own process, with its own API routes, static assets, and an extension-scoped token.
suwu gqruns the same sandbox from the command line. -
Installable extras —
suwu installputs backgrounds and extensions into the data directory, from a picker over the first-party catalog or from a zip. Archives are validated with the same resolvers the server uses, so a broken install never lands. -
Your settings survive the browser — System Settings → Backup keeps a copy of your settings and extension data on the server, encrypted in the browser with a passphrase the server never sees. It refreshes on a timer, keeps the last ten versions, and a new browser comes back exactly as you left it.
curl -fsSL https://raw.githubusercontent.com/liyu1981/suwu/refs/heads/master/install.sh | shThis downloads the latest release binary to ~/.local/bin/suwu and runs
an interactive suwu onboard wizard. Onboarding requires an attached
terminal; it collects the complete setup plan, shows a review, and only then
writes configuration or installs selected tools.
To change one part of an existing setup without re-running the whole wizard, pass a section flag:
suwu onboard --password # reset the connection password
suwu onboard --server # bind host, ports, session timeout
suwu onboard --tls # TLS certificate
suwu onboard --runtime # data directory and systemd service
suwu onboard --tools # development tools
suwu onboard --shell # shell integrationSection runs prompt only for that part, show the resulting configuration, and leave every other setting as it is on disk. Flags can be combined.
To set up a second machine from here, suwu install-to copies this binary to
it over SSH and runs the remote onboarding wizard with this terminal attached:
suwu install-to alice@192.168.0.5
suwu install-to --port 2222 --identity ~/.ssh/suwu_ed25519 deploy@server.lanThe transfer is refused when the remote platform does not match this binary
(uname -sm vs. GOOS/GOARCH); on a match the file lands in
~/.local/bin/suwu. Authentication uses the ssh-agent, ~/.ssh keys, or a
password prompt on this terminal. The SSH connection closes when the wizard
finishes or on any error.
pnpm start # install deps, build web assets + server, run on HTTPS :8181Or build and run manually:
pnpm build # install deps, vite build -> pkg/assets/web, go build -o suwu ./cmd/Suwu
./suwu serve # production: https://127.0.0.1:8181pnpm build (and start, build:max, build:ext) runs pnpm install for the
workspace first, so pulling a change that adds or bumps a dependency needs no
separate install step. It is a no-op when the lockfiles are already satisfied,
and pnpm freezes the lockfile automatically when CI is set, so CI stays strict.
pnpm build:web alone deliberately skips it — that is the step the dev loop
(air) runs on every change.
The web assets are always embedded in the binary — a single suwu binary is
all you need to deploy.
Copy .env.example to .env and adjust. Shell environment variables take
precedence over .env.
| Variable | Default | Description |
|---|---|---|
SUWU_DEV |
false |
Dev banner and hot-reload mode. |
SERVER_MODE |
https |
https, http, or https+http. |
HTTPS_PORT |
8181 |
HTTPS listener port. |
HTTP_PORT |
8180 |
HTTP listener port. |
HOST |
127.0.0.1 |
Bind address. 0.0.0.0 exposes on all interfaces. |
EXTRA_HOSTS |
— | Comma-separated additional allowed hosts, e.g. example.com,*.lan.example. |
AUTH_PASS |
— | SHA-256 hash of the required web password; set by suwu onboard. |
DEMO_PORT |
8000 |
Port the Vite dev server proxies /api and /ws to. |
TLS_CERT_FILE |
— | TLS certificate for HTTPS modes. suwu gencerts writes both paths into ~/.config/suwu/.env. |
TLS_KEY_FILE |
— | TLS private key; must be set together with TLS_CERT_FILE. |
Browser-visible hostnames need no configuration: loopback names plus the
machine's own hostname and interface addresses are always accepted, so the
terminal works via localhost, the LAN IP, or the hostname out of the box.
suwu serve loads, in order of precedence: shell environment → ./.env
(project) → ~/.config/suwu/.env (user-global, created by suwu gencerts).
Serve a folder of static web assets through the running server and open it in a sandboxed browser tile:
suwu static-serve ./website # -> /staticserve/website/
suwu static-serve --list
suwu static-serve --pause website
suwu static-serve --resume website
suwu static-serve --remove websiteThe id comes from the folder name; another website becomes website1. The
registry is in memory, so entries disappear when the server restarts. Previews
need no token, but only the Host allow-list and loopback/recently-authenticated
browser IPs can read them. Served pages run in an opaque sandbox iframe and
root-absolute URLs such as /static/app.js return 404 instead of borrowing
Suwu's own assets.
Browsers only expose clipboard APIs (terminal paste) on secure contexts, so non-localhost HTTP access cannot paste into the terminal. To enable HTTPS:
suwu gencerts # interactive: pick hosts (auto-detected) and output dir
suwu serve # now serves https://, certs picked up automaticallygencerts creates a persistent local CA under ~/.config/suwu/CA/ and signs
a server certificate for the hosts you select (default
~/.config/suwu/tls-cert.pem + tls-key.pem). Client devices only need to
trust the CA once (~/.config/suwu/CA/rootCA.pem). Flags allow non-interactive
use: --hosts a.com,192.168.0.5 --out <dir> --no-env --force.
./serve-dev.sh start # hot-reload dev server (air): web + go rebuild on change
./serve-dev.sh status # resolved URL mirrors what the server actually binds
./serve-dev.sh logs # tail the log
./serve-dev.sh stopserve-dev.sh wraps pnpm dev (air), which rebuilds the web tree, rebuilds
the server into tmp/, and restarts on any source change. Logs and the PID
file live in var/.
For frontend-only iteration you can also run the Vite dev server directly — it proxies API and WebSocket traffic to the Go server:
pnpm run install:deps # dependencies for both workspaces (the dev loop skips this)
pnpm dev:web # Vite on :5173, proxying /api and /ws to DEMO_PORTpnpm test # go test ./...
pnpm vet # go vet ./...
pnpm typecheck # tsc --noEmit (frontend)cmd/Suwu/ entry point: flags, .env loading, graceful shutdown, banner
pkg/
assets/ go:embed of the built frontend (pkg/assets/web)
auth/ per-run same-origin token + host/origin validation
envfile/ minimal .env loader (first occurrence of a key wins)
pty/ shell PTY sessions (creack/pty)
session/ keyed PTY sessions with libghostty-vt screen state
vt/ libghostty-vt 1.0 binding (embedded official WASM, wazero)
server/ HTTP + WebSocket endpoints
assets/web/ built frontend (vite output, embedded into the binary)
frontend/ Vite + React + TypeScript + Tailwind v4
src/routes/ AppShell (header + content), TermPage (pane iframe)
src/wm/ tiling window manager: layout tree, shortcuts, tools
src/components/ FullTerminal, PTY session bridge, dialogs, hooks
src/store/ Jotai atoms (font, appearance, connection), shared
with pane iframes via localStorage storage events
- Auth: the server mints a fresh random token on every start. Browsers
fetch it from
/api/tokenbefore each connection attempt; WebSocket upgrades require the token plus a same-originHost/Origincheck, so cross-origin WebSockets are rejected. This server provides shell access — bind to loopback unless you understand the exposure. - Session reattach: each pane connects with a stable
sessionkey (the tiling pane id, persisted across reloads). The server keeps the shell and a libghostty-vt 1.0 screen model alive for a TTL (24 h by default,SESSION_TTL) after the last client detaches; reconnecting replays a VT dump of the screen and its retained scrollback before live output, so a refresh brings the pane back with its history. - Tiling: the layout is a tree of leaves (terminals) and split nodes with
flex weights, persisted in
localStorage. Panes render as same-origin iframes loading/term?pane=<id>, positioned absolutely from pixel rects computed by a purecomputeTiling()function. Shortcuts work both on the parent window and inside a focused pane (relayed viapostMessage).
- Suwu grants shell access to anyone who can reach the server and obtain the per-run token. It is designed for local development.
- Cross-origin WebSocket connections are rejected; browser-visible hosts are limited to loopback and the machine's own hostname/interface addresses.
- Binding beyond loopback exposes the shell to everyone who can reach the machine's network.
- Only run Suwu on networks and machines you trust.
Questions, tips, and show-and-tell: join the Suwu community on Reddit.







