Skip to content
KortixKortix
Esc
↑↓navigate↵open⌘Jpreview
On this page

TUI

kortix tui: the full Kortix client in your terminal, with sessions, a real sandbox shell, files, review, Apps and settings.

kortix tui opens the Kortix client in your terminal. A sidebar lists accounts, projects and sessions. The session view has the transcript, the composer, and a shell in the session’s sandbox. The Files, Review, Apps, Customize and Account screens are one key away. It reads the same data as the web app, so a session in the terminal is the same session in the browser. The TUI is experimental: its screens, keys and flags can change between releases.

Use it when you work from a terminal and want to drive sessions with the keyboard. For one-shot commands and scripts, use the CLI.

Start the TUI

kortix login     # once, if you have not signed in
kortix tui       # or: kortix t, or: kortixt

kortixt (one word) is a link to kortix that the installer adds. It runs kortix tui with the arguments you give it. Bind it to a key in your terminal.

Open a new session in a project, with the sandbox shell open and focused:

kortixt --project <project_id> --new --terminal

The new session uses the project’s default agent. Add --agent <name> to pick another.

The TUI uses the CLI’s login: the active host, or the host that --host names. With no host logged in, it opens its own login screen. Press Enter on a configured host, or press n to add one with a name, an API URL and a token. The TUI checks the token before it saves the host.

The terminal must be at least 80 × 24.

Install and update

The TUI is a separate binary, kortix-tui, of about 80 MB. The kortix binary does not include it.

  1. The first kortix tui asks before it downloads. Enter means yes.
  2. It downloads the kortix-tui build that matches your CLI version from the same GitHub release as kortix.
  3. It verifies the binary against the release’s .sha256 file before it makes the binary executable.
  4. It stores the binary in ~/.kortix/tui/<version>/kortix-tui. Later runs start the stored copy.

After you update the CLI (kortix update), the next kortix tui gets the matching build with no prompt. When the new release has the same binary, it reuses the copy it has and downloads nothing. It removes the old versions.

In scripts and Dockerfiles, run kortix tui --install: it installs with no prompt and exits. kortix tui --uninstall and kortix uninstall remove ~/.kortix/tui/.

Prebuilt binaries exist for macOS and Linux, on arm64 and x64. The TUI does not run on other platforms.

When the launcher cannot install:

Situation Result
No terminal (a pipe, CI) and no installed version Exits 2 and prints kortix tui --install. Nothing downloads. An installed older version updates with no prompt, also without a terminal.
Inside a Kortix session sandbox Refuses to install and exits 1. Run kortix tui on your own machine, or set KORTIX_TUI_BIN.
You answer no to the prompt Exits 0. Nothing is installed.
The download or the checksum fails Exits 1. Nothing is left in the cache.
A kortix built from source (version dev) Exits 1. No release matches it. Build the binary with pnpm --filter @kortix/tui bundle and set KORTIX_TUI_BIN, or copy it to ~/.kortix/tui/dev/kortix-tui.

Flags and environment

Flag Effect
--host <name> Use this configured host instead of the active one. A host that is not logged in exits 1 with kortix hosts login <name>.
--project <id> List this project’s sessions. Default: the host’s default project, else its first project.
--session <id> Open this session at boot. Without --project, the launcher finds the session’s project on the hosts you are logged into.
--new Create a session in the project at boot and open it.
--agent <name> Agent for the --new session. Default: the project’s default agent.
--terminal Open the sandbox terminal panel at boot, focused.
--no-sidebar Start with the sidebar hidden. Alt+B shows it. Same as KORTIX_TUI_SIDEBAR=0.
--mouse Let the TUI take the mouse. See Mouse. Same as KORTIX_TUI_MOUSE=1.
--install Install the binary and exit.
--uninstall Remove ~/.kortix/tui/ and exit.

The launcher takes options only. A bare argument is an error that exits 2.

Variable Effect
KORTIX_TUI_THEME dark or light. Unset: the terminal’s COLORFGBG decides, else dark.
KORTIX_TUI_AUTO_FORWARD 0 turns off port auto-forwarding. See Ports and links.
KORTIX_TUI_BIN Path to a kortix-tui binary to run. Nothing downloads and no version check runs.
KORTIX_API_KEY A token. With it, the TUI does not read the CLI login.
KORTIX_TOKEN The same as KORTIX_API_KEY. KORTIX_API_KEY wins when both are set.
KORTIX_API_URL The API origin. With KORTIX_API_KEY or KORTIX_TOKEN, it defaults to https://api.kortix.com. Without them, it overrides the URL of the CLI’s active host.

The TUI picks its host in this order: --host, then KORTIX_API_KEY or KORTIX_TOKEN, then the CLI’s active host. A KORTIX_TOKEN that stays exported in your shell, for example from a sandbox session, outranks kortix login. When the API rejects it, the TUI opens the login screen and names the variable. Run unset KORTIX_TOKEN, or pick a stored host.

Screens and keys

Press ? for every binding. These keys work on every screen:

Keys Action
Alt+F Files: the sandbox workspace tree and a file viewer.
Alt+R Review: open change requests and their diffs. Merge or close from here.
Alt+A Apps: the project’s Apps, their status and URLs.
Alt+C Customize: agents, skills, secrets, triggers and connectors.
Alt+U Account: members, invites, roles and billing.
Alt+T Show or hide the sandbox terminal panel beside the transcript.
Alt+P Open the Ports panel.
Alt+L Open the Links panel.
Ctrl+P Open the switcher: one filter over every session and project.
Ctrl+N Create a session in this project and open it.
Alt+B Hide or show the sidebar. Ctrl+P still works while it is hidden.
Alt+O Attach the session in the OpenCode TUI. See Attach the OpenCode TUI.
Alt+H Switch host. Ctrl+H also works in a terminal with the kitty keyboard protocol.
Tab / Shift+Tab Focus the next or previous region: sidebar, transcript, composer, terminal.
Esc Close the overlay, leave the screen, or move focus back to the composer.
? Show every binding. Not while the composer or the terminal has focus.
Ctrl+C twice, or Ctrl+Q Quit.

In the composer:

Keys Action
Enter Send the draft. While the agent works, queue it.
Ctrl+J, Alt+Enter Insert a newline in every terminal. Shift+Enter works only with the kitty keyboard protocol.
Esc Clear the draft. With an empty draft while the agent works, press Esc twice to stop the agent.
/ At the start of the draft, open the command picker.
Alt+M, Alt+E, Alt+G Pick the model, the thinking effort, the agent.

A permission prompt in the transcript takes y (allow once), a (allow always) or n (deny).

Alt is Option on macOS. In Terminal.app, turn on Use Option as Meta key.

The terminal panel keeps its keys. When the panel has focus, the shell receives every key, Ctrl+C included. The app keeps only Tab, Shift+Tab, Alt+T, Alt+P, Alt+L and Ctrl+Q. Quit with Ctrl+Q, or press Alt+T to hide the panel first.

Ports. When a sandbox port shows up in the transcript or in the terminal panel, the TUI forwards it to the same port on your machine, or to the next free port. It detects localhost, 127.0.0.1 and 0.0.0.0 followed by a port, with or without http:// or https://. A toast confirms each forward, and the status bar lists the forwarded ports (⇄ 3000, 5173).

  • It ignores ports 1–1023, except 80 and 443.
  • It ignores 22 (SSH) and 8000 (the sandbox’s own service port).
  • KORTIX_TUI_AUTO_FORWARD=0 turns auto-forwarding off. You can still add ports in the panel.
  • Forwards belong to the open session. They close when you switch sessions or leave the session view.

Alt+P opens the Ports panel. It shows one row per port, its state and its local URL.

Key Action
Enter Forward the selected port, or stop it.
o Open http://localhost:<port> in the browser.
y Copy the local URL.
a Add a sandbox port by number.
Esc Close the panel. Forwards keep running.

From the CLI, kortix sessions forward <session_id> --port <sandbox>[:<local>] forwards a port the same way. For previews in the browser, see Sandboxes & previews.

Links. A long URL in the terminal panel wraps across rows, so your terminal cannot open it as one link. A sign-in URL from gh auth login or codex login is the usual case. Alt+L opens the Links panel: every http and https URL in the transcript and on the terminal screen, with wrapped rows joined, newest first. Alt+L works while the terminal panel has focus.

Key Action
j / k, g / G Move the selection.
Enter or o Open the URL in the browser.
y Copy the URL.
Esc Close the panel.

Mouse

The TUI does not take the mouse by default. Your terminal’s own selection, copy-on-select and Cmd+click or Ctrl+click on a URL keep working, as in a plain shell. Nothing in the app needs a click.

kortix tui --mouse (or KORTIX_TUI_MOUSE=1) gives the mouse to the app. Then, in most terminals, hold Shift and drag to select text.

Attach the OpenCode TUI

Attach hands the session to the stock OpenCode TUI. Use one of these:

  • Alt+O on the open session.
  • a on a session row in the sidebar.
  • /attach in the composer.

The first attach downloads the OpenCode version that the sandbox runs. It stores it in ~/.kortix/opencode/<version>/. Later attaches reuse it. A local proxy adds your Kortix token to each request. A session that is not running starts first, and attach waits until its sandbox is ready.

While OpenCode has the terminal, the Kortix TUI paints nothing. To leave OpenCode, press Ctrl+C twice within 1 second. Esc does not leave it. The Kortix TUI then returns to the same session.

A session on the pi harness has no attach. Alt+O and a show a notice, and /attach is not in the command picker. a on a pi session that is not open starts its sandbox first, then shows the notice. Use Alt+T for a shell in its sandbox. See Harnesses: OpenCode and pi.

From the CLI, kortix connect <session_id> attaches the same way. It does not start a stopped session: run kortix sessions restart <session_id> first.

Known limits

  • @path mentions in the composer are counted (@n) but not uploaded.
  • Account and Customize are read-mostly. They do the small edits the web app offers there, such as adding a secret, pausing a trigger or inviting a member, and print the web URL for the rest. Connector sign-in happens in the browser.
  • A new session shows Untitled until the server names it after its first turn.

Was this page helpful?