TUI

Experimental. kortix tui installs a separate binary on first run, and its keys, screens and flags can change without a deprecation.

@kortix/tui is a full terminal client for Kortix. It renders with OpenTUI on Bun and reads every byte of Kortix data through @kortix/sdk — the same package the web app uses — so a session in the terminal is the same session in the browser.

It mirrors the web product: a sidebar of accounts, projects and sessions; a transcript with the composer, the model, effort and agent pickers, and the question and permission prompts; a real shell in the session's sandbox; and the Files, Review, Apps, Customize and Account screens.

Run it

kortix login          # writes ~/.config/kortix/config.json
kortix tui            # first run: "Install now? [Y/n]"
kortix t              # the short spelling
kortixt               # one word, installed beside kortix — bind it to a key

# One keystroke to a cloud engineering desk: a new session in the project,
# with its default agent (or --agent <name>), the sandbox shell open.
kortixt --project <project-id> --new --terminal

kortix tui signs in with the host you are already on, so there is nothing to configure. It is a launcher: the TUI itself is a second binary, kortix-tui, because the renderer's native library adds ~19 MB per platform and kortix should not carry it for a command most people never run.

The first kortix tui asks before downloading. It fetches the kortix-tui build that matches this CLI's version from the same GitHub release the kortix binary came from, checks it against the release's .sha256, and stores it in ~/.kortix/tui/<version>/. After a CLI update the TUI updates itself with no prompt, reuses the installed copy when the release did not change it, and removes the old versions. That takes a few seconds once per CLI version; every later run execs the cached copy. A kortix that cannot reach GitHub, or a platform with no published build, is the one case where you build your own — see KORTIX_TUI_BIN below.

Off a terminal — a pipe, CI, a non-interactive shell — kortix tui never starts the download on its own. It exits 2 and prints kortix tui --install.

With no host logged in at all, the TUI opens its own login screen instead of failing: pick a configured host, or press n to add one (name, API URL, token — validated before it is saved).

The terminal needs at least 80 × 24.

To run it from a clone of the repo instead — which is what you want when you are changing the TUI itself:

git clone https://github.com/kortix-ai/suna
cd suna
pnpm install
pnpm --filter @kortix/tui dev

That path needs Bun 1.3 or newer: @opentui/core ships a Bun-FFI native renderer.

Environment variables

These apply to pnpm --filter @kortix/tui dev. The environment beats the config and writes nothing to disk, which is what a script or a second host wants. Under kortix tui the CLI resolves the host, so --host, --project and --session are the equivalents — with one exception: KORTIX_TOKEN is read by the CLI too, and a stale one left exported in a shell outranks kortix login for both.

KORTIX_API_URL=http://localhost:8008 KORTIX_API_KEY="$TOKEN" \
  pnpm --filter @kortix/tui dev

Building the TUI binary yourself

A source checkout, an unpublished platform, or an offline machine:

pnpm --filter @kortix/tui bundle       # → apps/tui/bundle/kortix-tui
KORTIX_TUI_BIN=$PWD/apps/tui/bundle/kortix-tui kortix tui

pnpm --filter @kortix/tui bundle:all builds all four release targets (kortix-tui-darwin-arm64, kortix-tui-darwin-x64, kortix-tui-linux-x64, kortix-tui-linux-arm64) — the same command the release workflow runs.

A kortix built from source reports version dev and has no release to match, so it refuses to invent a download. Copy your build to ~/.kortix/tui/dev/kortix-tui and kortix tui finds it with no environment variable at all.

Screens

Keys

? prints the full table — 155 bindings across fourteen scopes — generated from the app's own keymap, so a binding that is not in the overlay does not exist. These are the ones that work anywhere:

Two terminal facts shape that table:

• Alt is Option on macOS. Terminal.app and iTerm2 send Alt+T as the two bytes ESC t. The keymap accepts that and the kitty encoding, so every Alt chord works in both. In Terminal.app, turn on Use Option as Meta key.
• Ctrl+H is the ASCII backspace byte. A terminal without the kitty keyboard protocol cannot tell the two apart, which is why Alt+H is the host switcher's first chord. Shift+Enter has the same problem: Ctrl+J is the portable newline and always works.

Inside the terminal panel the shell keeps every key, Ctrl+C included. Only Tab, Shift+Tab, Alt+T, Alt+P, Alt+L and Ctrl+Q stay the app's.

Ports

VS Code-style local port forwarding: a sandbox port a session's agent mentions (http://localhost:3000, a bare 127.0.0.1:5173, a 0.0.0.0:PORT banner) is auto-forwarded to the same local port — or the next free one — the moment it's noticed in the transcript or the terminal panel's output. A toast confirms it: Forwarded localhost:3000 → sandbox:3000. Set KORTIX_TUI_AUTO_FORWARD=0 to turn this off and forward only by hand.

Detection ignores ports 1-1023 except 80 and 443, and the sandbox's own SSH (22) and OpenCode control (8000) ports.

Alt+P opens the panel: one row per port, its state (forwarding / stopped / error), and its local URL when forwarding. Enter toggles the selected port, o opens http://localhost:<port> in the browser, y copies the local URL, a adds a port by number regardless of auto-forward, and Esc closes the panel without stopping anything. The status bar shows ⇄ 3000, 5173 while any port is forwarding.

Forwards are per session: they close when the session view unmounts or the session changes. The panel reuses the exact same engine as kortix sessions forward — one implementation, two front ends.

Links

The terminal panel is a VT emulator drawn into cells, so the host terminal cannot click inside it: a URL longer than the panel wraps across rows, and Ghostty or iTerm2 sees several unrelated rows, never one link. An OAuth sign-in URL a CLI prints (codex login, gh auth login) is the common case.

Alt+L opens the Links panel — every http(s):// URL in the transcript (assistant text and tool output) and on the terminal screen right now, wrapped rows rejoined, newest first:

Alt+L works while the terminal panel is focused, so the URL a CLI just printed is one chord away. Only http: and https: URLs are opened.

Mouse, selection and copying

The TUI does not take the mouse. Your terminal's own text selection, copy-on-select and Cmd/Ctrl+click on a URL therefore keep working inside it, exactly as in a plain shell; in Ghostty that means drag to select and the selection is on the clipboard. Nothing in the app needs a click. kortix tui --mouse (KORTIX_TUI_MOUSE=1) gives the mouse to the app instead, and then Shift+drag is the way to select natively in most terminals.

The sidebar can be hidden: Alt+B toggles it, kortix tui --no-sidebar (KORTIX_TUI_SIDEBAR=0) starts without it. Ctrl+P still switches sessions and projects while it is hidden, and the status bar shows Alt+B sidebar.

Attach mode

Alt+O — or a on a sidebar row, or /attach in the composer — hands the session to the stock opencode TUI. The TUI resolves the session's runtime, downloads the exact opencode build that sandbox runs into ~/.kortix/opencode/<version>/ once, starts a localhost proxy that injects your Kortix token, and suspends itself while opencode has the terminal. On exit the Kortix TUI repaints on the same session and toasts the exit code. It is the same seam as kortix sessions connect.

The first attach is slow because of that one download. A session that is not running is started first, and a cold sandbox boot is minutes, not seconds.

Leaving opencode is Ctrl+C twice within one second — Esc does not do it, and two presses spaced further apart are two separate interrupts that opencode ignores. The Kortix TUI repaints as soon as opencode exits.

Known gaps

• @path attachments are parsed but not sent. The composer counts mentions and shows @n; the SDK's attachment surface is browser-File shaped, so a path is not uploaded yet.
• Effort options come from the model's catalog variants. A model that publishes none offers Auto alone. That is the catalog's answer, not a bug.
• The Account and Customize screens are read-mostly. They expose the small writes the web app exposes and print the web URL for anything else. No OAuth from the terminal: connectors print the page to open.
• The session header has no name until the server sets one. A new session reads Untitled for a few seconds.

Source

apps/tui in the Kortix repo. The launcher is apps/cli/src/commands/tui.ts, and apps/cli/src/tui-bin.ts resolves, downloads and verifies the binary. SPEC.md there is the plan, README.md is the operator's guide (every key, every troubleshooting path), and docs/opentui-notes.md records the OpenTUI behaviors the app had to work around.