Documentação

Sessions

Creating, listing and attaching to sessions.

Nesta página

Overview

A session is a persistent TDE desktop that outlives your terminal. A supervising host process owns a PTY, runs the desktop inside it, and publishes a Unix socket that clients attach to. Close your SSH connection, reconnect an hour later, attach again — the same windows are still there.

tde session is on the operations side of the CLI split, so it does not take --json or the semantic envelope. Several of its verbs print JSON anyway, in their own shape.

bash

tde session start
tde session attach

Every verb takes an optional session name; it defaults to default. Names are restricted to ASCII letters, digits, -, _ and ., and may not contain .., because the name becomes a directory under ~/.tde/sessions/.

Commands

text

tde session start   [name] [--wait] [--timeout SECONDS]
tde session attach  [--legacy] [name]
tde session service <systemd|launchagent|install> [name]
tde session <host|status|list|restart|stop|kill|cleanup|logs> [name]

Verb	What it does
`start`	Spawns the host process in the background and prints its pid, or reports that the session is already running.
`attach`	Connects this terminal to a running session. Detach with Ctrl-].
`status`	Prints one session's state as pretty JSON. This is the default when no verb is given.
`list`	Prints the same JSON object for every session in `~/.tde/sessions/`, as an array.
`restart`	Stops the session, cleans its files, and starts it again.
`stop`	Asks the session to shut down; reports if it was not running.
`kill`	Stops it, then removes its files — but only once it has actually stopped.
`cleanup`	Removes the session's leftover files without touching any process.
`logs`	Prints the session's log file to stdout.
`host`	Runs the supervising host in the foreground. This is what `start` spawns.
`service`	Prints or installs a user service unit so the session starts at login.

--wait on start blocks until the socket is connectable and the session reports Running, then prints a readiness line. --timeout SECONDS bounds that wait and defaults to 30 seconds. Both are ignored by verbs that do not wait.

Reading session state

status and list return the same object per session:

json

{
  "name": "default",
  "pid": 24601,
  "host_pid": 24598,
  "socket_exists": true,
  "log_path": "/home/you/.tde/sessions/default/desktop.log",
  "state": "Running",
  "generation": 3,
  "heartbeat": { "status": "running", "…": "…" },
  "host_identity": { "pid": 24598, "…": "…" },
  "desktop_identity": { "pid": 24601, "…": "…" }
}

pid is the desktop child, host_pid is the supervisor. The generation counter increases each time the session's desktop is replaced, and the two *_identity objects carry a verified process fingerprint — pid, start time and executable — not just a number. That verification is what lets kill refuse to delete state belonging to a process it cannot prove is the right one.

Session files

Each session owns a directory under ~/.tde/sessions/<name>/:

File	Purpose
`session.sock`	The Unix socket attach clients connect to.
`host.pid`	Pid of the supervising host process.
`desktop.pid`	Pid of the desktop child running inside the PTY.
`desktop.log`	What `tde session logs` prints.

cleanup removes these; kill removes them only after confirming the processes are gone, and leaves them in place otherwise so a still-live session is never orphaned from its own state.

tde session service renders — or installs — a user-level service definition so a session comes back after a reboot.

bash

tde session service systemd            # print the unit to stdout
tde session service launchagent        # print the macOS plist to stdout
tde session service install            # write it for the current platform

install writes the unit or plist with owner-only permissions and then prints the command that enables it: systemctl --user enable --now tde-session-<name>.service on Linux, launchctl load <path> on macOS. Nothing is enabled for you. Any other subcommand — including none at all, which defaults to systemd — prints the usage block.

Attaching from an older client

tde session attach --legacy performs the older, pre-generation handshake instead of the current authenticated one. It exists for compatibility with clients that predate session metadata; a current TDE talking to a current session should never need it. The flag may be given at most once, and it can appear before or after the session name.

Sessions and the Runtime

Sessions and the Runtime are different long-lived processes and are worth keeping straight. A session keeps a desktop alive so a human can reattach to it. The Runtime keeps pipeline execution alive so work continues when no desktop exists at all. You can run either without the other; My Loop tasks keep running whether or not a session is attached.