Suwu

Security & Data

Where Suwu stores your data, what it has access to, and important security considerations.

Important — Read This

Suwu is designed for use on intranets and trusted private networks. It gives anyone with access a full shell on the host machine. Do not expose Suwu directly to the public internet unless you know exactly what you are doing and have appropriate zero-trust controls in place.

Where Data Is Stored

Suwu keeps all its data under your home directory. Nothing is sent to external servers (except binary updates from GitHub).

Path Contents
~/.local/bin/suwu The Suwu binary
~/.config/suwu/.env Environment configuration (host, port, TLS paths, password hash)
~/.config/suwu/theme.json Custom theme (optional)
~/.config/suwu/sessions/ Persisted terminal sessions, tile layouts, scrollback buffers
~/.config/suwu/certs/ Self-signed TLS certificates (if generated)

What Suwu Has Access To

When you run suwu serve, the process runs as your user. This means:

  • Full shell access — every terminal tile is a real PTY with your user's permissions.
  • File system access — the file browser, file viewer, and suwu open can read and write any file your user can access.
  • Network access — port forwarding can bind to any port your user is allowed to use.
  • Environment variables — the shell inherits your environment, including any secrets in your shell profile.

There is no sandboxing. Suwu is a convenience layer on top of your existing shell, not a security boundary.

Authentication

  • Password auth — required by onboarding. Choose or generate it with suwu onboard; only its hash is stored in ~/.config/suwu/.env.
  • Per-run tokens — displayed at server startup, valid for the current run only.
  • Host validation — requests must use an allowed machine host or an EXTRA_HOSTS entry.

See Security & Access for full authentication and TLS setup details.

Network Exposure

Do Not Expose to the Public Internet

Suwu is not designed to withstand attacks from the open internet. It assumes a trusted network where all users are authorized. If you need remote access over the internet, use one of these approaches:

Put Suwu behind a zero-trust access proxy such as:

  • Tailscale — install Tailscale on the host, access Suwu via its Tailscale IP.
  • Cloudflare Tunnel — expose through Cloudflare's zero-trust network.
  • WireGuard — connect via a VPN, then access Suwu on the internal IP.

Alternative: Reverse Proxy with Auth

If you must use a public-facing reverse proxy (nginx, Caddy, etc.), add authentication at the proxy level:

  • HTTP Basic Auth or client certificate verification.
  • IP allowlisting.
  • Rate limiting.

Never expose Suwu on a public port without some form of authentication in front of it.

Session Data

Terminal sessions are persisted under ~/.config/suwu/sessions/. This includes:

  • Shell process state and environment.
  • Visible scrollback buffer (the text that was displayed).
  • Tile layout and working directories.

This data is stored in plain text on disk. If your machine is shared, other users with read access to your home directory could inspect session data.

TLS Certificates

If you generate self-signed certificates with suwu gencerts, they are stored in ~/.config/suwu/certs/. The private key is in plain text. For production use, provide your own certificates and restrict file permissions:

chmod 600 ~/.config/suwu/certs/key.pem

Updates

suwu upgrade downloads binaries from GitHub releases. The download is verified via checksum. No telemetry or usage data is sent.

Summary

Concern Status
Data leaves your machine No (except binary updates from GitHub)
Telemetry None
Sandboxing None — full user permissions
Authentication Optional (password, per-run token)
Session persistence Plain text on disk under ~/.config/suwu/
Designed for Intranet / trusted private network