FAQ¶

What state is restored after a restart?¶

• The layout: workspaces, tabs, window geometry, sidebar width/collapsed state, terminal font size, and each shell's last working directory.
• Each tab's scrollback (last ~5000 lines), replayed into a fresh terminal on restart with a dim ──── session resumed @ <time> ──── separator so the boundary between old output and the new shell is obvious.

Every tab respawns a fresh shell in the saved directory: running processes are not restored.

Can I turn scrollback persistence off?¶

Yes. It defaults to on, capped at 2 MB per tab, and the files are deleted when the tab or workspace is closed. To disable it entirely:

curl -X PATCH "http://127.0.0.1:<port>/api/ui?t=<token>" \
  -H 'Content-Type: application/json' \
  -d '{"scrollback_persist": false}'

The pref is persisted server-side, so it sticks across restarts.

Why didn't my Claude Code / vim / less / tmux session come back?¶

Full-screen TUIs draw into the terminal's alternate screen buffer, which the program owns and tears down when it exits. By the time terminux can save the tab, that buffer has been handed back and its contents are gone. On restart you'll see the shell session around the TUI: the commands, their non-fullscreen output, the prompt. iTerm2's session restoration has the same limit; alt-screen mode is specified that way.

What do the colored dots in the sidebar mean?¶

It's a small traffic-light:

• Blue: this workspace is the one you're currently looking at.
• Green: produced output since you last viewed it (go check).
• Amber: a foreground task is running and there's nothing else more urgent to signal. See Working vs ready.
• Empty outline: shell is at a prompt with nothing new.
• Gray: all shells in the workspace have exited.
• 🔔: a tab signaled it wants attention (BEL, OSC 9, or a long OSC 133;D). Overrides everything else.

Hover any dot for a tooltip with the same explanation.

What about split panes and Windows?¶

Both are still on the roadmap.

Does terminux work on Windows?¶

Not yet. macOS and Linux are supported; the Windows PTY backend is deferred.

Is it safe to expose terminux on the network?¶

By default the backend binds to loopback only and authenticates every request and WebSocket with a per-session token. If you bind beyond loopback (--host 0.0.0.0), that token is the only authentication: anyone with the URL gets a shell. Keep the URL private and prefer loopback.

Does terminux send any telemetry or need an account?¶

No. terminux is local-first: it stores everything in local files and never phones home.

Does it include an editor / AI / git integration?¶

No, and by design. terminux keeps a small, auditable surface: workspaces and tabbed terminals done well. Editor, AI, git, and file-navigator features are out of scope.

Why is the macOS app blocked by Gatekeeper?¶

The .app is ad-hoc signed only. On a Mac other than the build machine, right-click → Open the first time, or sign with a Developer ID and notarize. See Packaging & distribution.

Do I need Node.js to run terminux?¶

Only to build or change the frontend. The build output is committed to src/terminux/web/static/, so running from source needs only Python + uv (or pip).

Can I run terminux on a server and connect from my laptop?¶

Yes. Run terminux --server on the remote box and terminux --connect URL on your laptop. The shells live on the server (long-running builds keep going while your laptop sleeps or switches Wi-Fi); the laptop opens a native window pointed at the server's URL. The recommended setup uses an SSH tunnel to avoid exposing the server to the open internet. See Remote access for the full recipe.

terminux froze: what do I do?¶

A built-in watchdog detects an asyncio-loop stall after 3 seconds and automatically prints per-thread Python tracebacks to stderr (the same dump py-spy dump would produce). If you're running from the terminal you'll see them in place; if you launched from the .app, redirect stderr to a file:

uv run terminux 2>/tmp/term.log    # watchdog output goes here

To force a dump on demand without waiting for the watchdog:

ps aux | grep terminux | grep -v grep    # find the PID
kill -INFO <pid>                         # macOS
kill -USR1 <pid>                         # Linux

For a bug report, run the reproducer with --debug (slow-I/O warnings + access logs) or --trace (every persisted save and cwd lookup logged with its duration). Both flags emit ms-precision timestamps. See Debugging knobs for the full menu.