Getting started

Install the host

A release is an archive, kalareach-<target>-<release>.tar.gz, that holds the programs, the managed shell packages and a signed manifest, release.json, which the host checks before it takes the release in. On macOS and Linux, unpack it and run its own kr host install: the host keeps each release in a store of its own, and kr host update --archive moves it to a newer release without touching a live session. Each release carries the root that verifies the next one. A first installation has no earlier release to check against, so it takes the root the archive carries and checks the manifest against it. An update is checked against the root of the release it replaces, and the new release’s root must match that one or follow it, so a host whose current release carries none refuses every archive. On Windows the host executables and PowerShell packages are published in a signed archive with a checksum file, and each executable is signed and timestamped.

The companion application’s setup screen shows the graphical host, the headless host and a terminal profile as three separate choices, and it installs none of them itself. When you run kr host terminal-profile install with the identifier of a terminal application, as kr host terminal shows it (for example iterm2), the command adds a new profile named KalaReach to that application’s own list of profiles. Each window or tab opened with the KalaReach profile is a session of its own. The KalaReach profile will not become your default profile; your other profiles are left untouched. Also, the command does not modify any shell startup files, install services, or create login items. kr host terminal-profile remove takes out only what the install wrote. A window opened with the profile starts a session only when the shell integration below is installed and the host can start its control daemon; kr host terminal-profile status reports both as far as it can read them.

Installing the shell integration, kr shell install, 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, and it never installs a shell-wide exec kr hook, so 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 --shell-mode managed
# 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  live     managed          80x24   0 attachments  -               /home/sam/.local/share/kalareach/host/versions/0.1.0+7c68ef8cf3c0/shells/zsh/3f9a1c7e5b2d4086/bin/zsh
$ kr attach 1

In order to run the sample, a managed session needs the startup entry of its shell, and this can be added by running kr shell install. For the kr new command to succeed, a control daemon must either be running or be startable by the host. If the daemon is neither running nor startable, kr new answers HOST_NOT_CONFIGURED along with a message indicating how to resolve this. Running kr host startup --set standalone will cause kr new to launch the control daemon.

--shell-mode managed runs a KalaReach-qualified shell package as the session’s root shell, which is what gives the empty-prompt Ctrl-D below. Without it, kr new uses your host’s default mode, which is managed unless you chose another with kr host shell-mode; see the shell modes at the end of this page.

kr new takes at most 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. A command that revokes a device or a share, such as kr device revoke, names it by its identifier and never by a label or a number. kr close takes the display number or the identifier of the session, and --environment when that number names sessions in more than one environment.

--help works on every command, --json on every command, and --version on kr itself. A command that fails exits 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. The PowerShell package on Windows has no empty-prompt Ctrl-D; there, kr detach --attachment <id> detaches.

• Inside an application (an editor, a pager, an agent, a REPL) Ctrl-D keeps its native meaning and is forwarded unchanged.
• If you have any text entered in the root prompt, Ctrl-D will have its native meaning, and will not detach. Only an empty prompt can detach.
• Entering exit in the root shell, or the root shell failing will close the session. KalaReach will not restart it.

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.

There is a special case, which is related to logging out from a desktop. A session on the desktop profile is bound to that login context and closes with desktop_lost. A session on the headless profile reports what a logout does to it on your platform. On Linux with systemd user services it survives only if you have enabled lingering for your user with loginctl enable-linger, which KalaReach never does for you; without them the host does not establish what a logout does. Windows: the session will be closed when the user signs out. On macOS it outlives the graphical login, and the host reports how long it lasts after that as not established. kr doctor says which applies on your host. --invisible changes how a session is presented, not which profile it runs under, and it is never an implicit headless or logout-surviving mode.

Shell modes

--shell-mode native_compat runs the stock shell you name as the session’s root shell rather than a KalaReach-qualified one. A host uses it only when you ask for it, with this flag, the companion application’s creation sheet or kr host shell-mode, and never as a fallback. 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.

kr new prints the mode of the session it created, and kr list and kr status show it. A managed session on a host with no package for the shell you name is refused by name and never created as a stock shell. The companion application’s creation sheet shows the two modes side by side before anything exists.