Getting started

Install the host

KalaReach ships signed native packages for Linux, macOS and Windows, through package managers and as archives with checksums and signed manifests. Installation is deliberate about what it touches:

• It offers a graphical host, a headless host and terminal-profile creation as separate choices, so a server does not acquire a desktop integration it will never use.
• It records every integration it adds as a marked entry, and removal deletes only those entries. It never replaces .bashrc, redirects ZDOTDIR, substitutes an --rcfile or disables your existing profiles.
• It never installs a shell-wide exec kr hook. Your ordinary terminals stay ordinary.

The shell integration loads as a guarded addition to your normal interactive startup configuration, and it activates only inside a KalaReach root shell with a validated handshake. Child shells inherit neither the token nor the activation.

Create your first session

$ kr new --attach
session 1 · studio-mac · zsh · live
# This is your shell. Run anything you normally run.
$ cd ~/work/kalareach && codex
# Inside the agent, Ctrl-D still means what it means there.
# Once the agent exits you are back at the root prompt,
# and Ctrl-D at that empty prompt detaches instead of exiting.
$ kr list
1  fix pairing timeout   studio-mac  shell_ready  detached
$ kr attach 1

kr new takes exactly one presentation flag. --attach creates the session and attaches it to the terminal you are typing in. --terminal creates the session and opens your installed terminal application on it. --invisible creates it with no local terminal at all. When stdin and stdout are terminals the default is --attach; otherwise you must say which you meant.

The commands

Display numbers are allocated in order within an environment and are never reused. The protocol identifier remains the real identity. A number that is ambiguous across two environments fails with AMBIGUOUS_SESSION rather than picking the first match. Destructive commands take an explicit environment selector and a full identifier.

--help, --version and --json work everywhere, errors exit non-zero, and a literal -- ends KalaReach’s own option parsing.

Detaching with Ctrl-D

In a managed session, Ctrl-D detaches only at an empty root-shell prompt. That is the one place where pressing it would otherwise end your shell by accident.

• Inside an application (an editor, a pager, an agent, a REPL) Ctrl-D keeps its native meaning and is forwarded unchanged.
• At the root prompt with text already typed, Ctrl-D keeps its native meaning too. Only the empty prompt detaches.
• Typing exit at the root shell, or the root shell failing, closes the session. KalaReach does not restart it for you.

Closing a terminal window, detaching in an app and losing a connection all remove just that one attachment. The session stays live with no attachments at all.

What ends a session is the shell ending or the host stopping: kr close, an exit at the root shell, the root shell crashing, the worker failing, or a reboot. A host that sleeps suspends its work and resumes it on waking; it does not carry on while the machine is asleep.

Logging out of the desktop is a separate case. A session on the desktop profile is bound to that login context and closes with desktop_lost. A session on the headless profile reports whether its per-user service survives logout on that platform, and surviving logout is enabled only by an explicit choice during setup. --invisible changes how a session is presented, not which profile it runs under, and it is never an implicit headless or logout-surviving mode.

Compatibility mode

--shell-mode native_compat runs a stock shell instead of a KalaReach-qualified one. Create, attach, detach, close, file transfer, native agents and terminal presentation all keep working. Three things do not: Ctrl-D follows that shell’s own behaviour and can close the session, launch buttons print instructions instead of typing a command for you, and editor-buffer state is no longer authoritative. The difference is shown before the session is created and in kr status. It is never chosen for you.