The daemon¶
troupe-daemon is the local harness: the same code a worker pod runs, packaged for your
machine with its own Erlang runtime inside. The terminal client and the desktop app are
clients of it: a session on your machine runs here, speaks PROTOCOL.md
over a Unix socket, loopback TCP or a loopback WebSocket, and emits the same events a pod
does. Building it is in its README.
troupe-daemon [run] [--detached] serve on this machine until idle or stopped; --detached (Windows) with no console
troupe-daemon status say whether one is running, and where
troupe-daemon stop stop the one running here, between turns, and wait until it has
troupe-daemon open [--url URL] start it if need be, and open the web app connected to it
troupe-daemon config the resolved providers and models (keys masked)
troupe-daemon config --explain [KEY] [--json] every setting, or KEY's, and which file set it
troupe-daemon config validate [PATH] check the config files, or one; exits 1 on any problem
troupe-daemon config migrate [--write] [PATH] show, or make, the rewrite to the current spellings
troupe-daemon config trust [PATH] let a workspace's own files set the trusted keys; --list shows them
troupe-daemon config untrust [PATH] take that back
troupe-daemon config import-opencode copy opencode's providers into config.yaml
troupe-daemon models [--refresh] what each provider serves; asked again when stale, or now with --refresh
troupe-daemon doctor check the setup: provider, key, models, daemon, PATH, plane; exits 1 on a failure
troupe-daemon login on|off|status start at login, or not; status exits 1 when it does not
troupe-daemon version
troupe-daemon is a shell wrapper in the release's bin/: run is the release's
start, everything else is eval in a second short-lived VM that starts no daemon.
Clients start it themselves: Troupe.Protocol.Daemon (Elixir) and the desktop shell find
troupe-daemon on the PATH and spawn run when nothing answers. run is idempotent —
a second one on a machine with a daemon already up says where it is and exits 0. On
Windows a daemon a client starts runs in a console window of its own, minimised to the
taskbar: closing the terminal it was started from leaves it running, and closing its own
window stops it
(Decision 802).
One started at login has no window at all: run --detached starts the VM detached from
any console, the runtime's own erl -detached
(Decision 962).
Install¶
The installers' two commands are in the quick start. The
daemon is always installed. In a terminal the installer asks whether to add the TUI,
the desktop app and the VS Code extension, shows what it is about to do, and asks before
doing it; --tui, --gui and --vscode (-Tui, -Gui, -VSCode) name them, and -y
(-Yes) asks nothing, installing the daemon alone when none is named. Once the daemon is
in place it asks whether to start it at login, Enter meaning no;
--start-at-login and --no-start-at-login (-StartAtLogin, -NoStartAtLogin) answer
without the question, and -y alone turns nothing on.
The copy attached to a release installs that release, and TROUPE_VERSION=0.15.0-beta
names another (with minisign installed, none from before 0.13, which were not signed). A
private repository answers /releases/latest only to somebody signed in, so there the
installers ask for TROUPE_VERSION, and TROUPE_RELEASE_URL names a mirror. Each release
at https://github.com/it-minds/troupe/releases carries
troupe-daemon-<version>-<target>.tar.gz, the troupe binaries and one SHA256SUMS,
which both installers check every download against before replacing anything (and the
release's signature where minisign is installed, updating).
The release unpacks to ~/.local/lib/troupe-daemon (%LOCALAPPDATA%\Programs\troupe-daemon)
with troupe-daemon linked into ~/.local/bin (a .cmd shim in
%LOCALAPPDATA%\Programs\troupe, on the user PATH). Both installers keep the previous
release beside the new one for rollback, and take --uninstall / -Uninstall (with
--purge / -Purge, the settings and session logs too). The release needs nothing
beyond what the tarball carries.
Start at login¶
troupe daemon login on has the daemon start every time you log in, and login off takes
that back; login status says which. The installers ask the same thing once the daemon
is installed, and so do the first run's questions, in the desktop app and in
troupe config; --uninstall (-Uninstall) runs login off before it removes anything
(Decision 818).
Each platform gets its own per-user entry, and none needs an administrator
(Decision 762):
| Platform | The entry |
|---|---|
| Windows | troupe-daemon.cmd in your Startup folder (%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup), which runs troupe-daemon run --detached: no window, the daemon's VM detached from any console; troupe-daemon stop stops it, its log is daemon.log in the state directory, and Task Manager's Startup list shows the entry |
| macOS | a launchd agent, ~/Library/LaunchAgents/com.objective-mj.troupe.daemon.plist |
| Linux with systemd | a user unit, ~/.config/systemd/user/troupe-daemon.service, enabled for default.target |
| Linux without systemd | an autostart entry, ~/.config/autostart/troupe-daemon.desktop, which a desktop session starts |
The entry runs troupe-daemon run — the one on the PATH, as a client finds it — with
TROUPE_DAEMON_IDLE_MINUTES=0, so a daemon started at login stays up until you log out
rather than exiting when idle. Turning it on takes effect at the next login and starts
nothing now; turning it off removes the file and stops nothing that is running. An entry
from an earlier daemon (on Windows one that opened a minimised console window) is written
again in this version's shape the first time the daemon starts after an update, and the
daemon's log says so; one that starts another install's daemon is left alone.
The web app¶
A page in a browser cannot read daemon.json or start a program, so troupe-daemon open
does both for it: it starts the daemon if none is answering, then opens your browser at
the web app with the loopback WebSocket's port and token after a #. The page connects,
takes them off its address bar and keeps them in the browser, so a reload or a new tab
connects again; the token changes every time the daemon starts, and running open again
hands over the new one. Nothing printed names the token.
The web app is --url's, or the one the plane the daemon is linked to says it serves (its
/.well-known/troupe), or, from a plane that does not say or does not answer, the one at
its /app/; --url is needed when the daemon is not linked. The
daemon admits that page's origin by itself, as it admits the linked plane's
(Decision 797); an
upgrade it refuses is a warning in its log, naming the origin. BROWSER, where it is set,
is what the address is opened with; on Linux and macOS the browser is given a page that
only you can read, which sends it on, so the token is never on a command line.
Configuration¶
The daemon reads the same files as every client: the organisation's defaults, your
config.yaml, a project's .troupe/config.yaml and .troupe/config.local.yaml, then
TROUPE_*, merged by key, and what the organisation enforces over all of them; a
project's files set the trusted keys only in a workspace you trust, and a pod's never do.
The layers, every key and the commands above are on
configuration, with a gateway's file among the
examples; troupe-daemon models and its
cache on models and providers.
| variable | meaning |
|---|---|
TROUPE_PROVIDER, TROUPE_MODEL, TROUPE_BASE_URL, TROUPE_API_KEY / TROUPE_AUTH_TOKEN |
the session-wide provider (all of them) |
TROUPE_DAEMON_IDLE_MINUTES |
exit after this long with nothing running; 0 never (default 10) |
TROUPE_SESSION_IDLE_MINUTES, TROUPE_SESSION_DETACHED_MINUTES |
when a session goes to sleep, watched and unwatched (below) |
TROUPE_CLIENT_TOOL_GRACE_SECONDS |
how long a call to a client's own tool waits for that client to come back (below) |
TROUPE_DAEMON_LOG |
file (default: daemon.log in the state directory, beside the TUI's troupe.log) or stderr |
TROUPE_LOG_LEVEL |
debug, info, warning, error |
TROUPE_STATE_HOME, TROUPE_CONFIG_HOME |
where sessions and config live |
TROUPE_ALLOWED_ORIGINS |
the origins admitted at the loopback WebSocket, in place of localhost, the desktop shell, the linked plane and the pages open opened |
BROWSER |
what troupe-daemon open opens the web app with, in place of the system's default browser |
The daemon is not a distributed Erlang node (rel/env.sh.eex sets
RELEASE_DISTRIBUTION=none): no name, no epmd, no port beyond its own two.
How long it stays up¶
A daemon a client started has to go away by itself, and a laptop is not quiet until it
has. This is the whole ladder, from a running turn down to the daemon's exit; each rung
has one clock, and the three modules that keep them (Troupe.Session.ClientTools,
Troupe.Sessions.Index, Troupe.Gateway.Idle) point here rather than saying it again.
| Rung | After this long | Set by | Default |
|---|---|---|---|
| a turn runs | never stopped for it — a model call or a tool, whether anybody is attached or not | ||
| a tool call ends | the tool's own timeout: shell_timeout_ms for a shell command and for a client's own tool; the agent cuts any tool a minute after that, three minutes at least |
shell_timeout_ms (configuration) |
2 min |
| a client's own tool call whose client left is failed | nobody has offered the tool again within the grace, which comes out of the call's timeout; a client back inside it is asked the same call | TROUPE_CLIENT_TOOL_GRACE_SECONDS (:troupe_core, :client_tool_grace_ms); 0 fails it at once |
60 s |
| a session sleeps, read | never, while a client is subscribed to it by name: a session is not stopped under the person looking at it, and the clocks below start when they leave | ||
| a session sleeps, watched | idle or waiting on a person, with somebody following it but not reading it — a fleet subscriber, watch mode |
TROUPE_SESSION_IDLE_MINUTES (:troupe_core, :session_idle_ms) |
30 min |
| a session sleeps, unwatched | the same, with nobody watching it | TROUPE_SESSION_DETACHED_MINUTES (:troupe_core, :detached_idle_ms) |
2 min |
| the daemon exits | no client connected, no session awake and none offered for steering from another device; never for one started at login (above) | TROUPE_DAEMON_IDLE_MINUTES (:troupe_daemon, :idle_shutdown_ms) |
10 min |
troupe-daemon stop does not wait for the last rung: it asks the daemon running here to
stop between turns, as troupe update does, waits while a turn is at work and until
nothing answers, and leaves a daemon a TUI runs inside itself, exiting 1.
0 means never on the minute clocks. A session that sleeps stops its tree and keeps its
log: the next command that acts on it — input, an answer, an approval — brings it back,
and an approval or a question it was waiting on is asked again rather than failed, so it
can be answered days later. Reading it (listing, subscribing, its history) wakes nothing.
In a session that is still awake, a call waiting on a person is failed as timed out after
the tool's own timeout — one reason an unwatched session sleeps before then. What ended
or was asked while nobody was reading a session is in its session.list row as unseen
(PROTOCOL.md), for the client that comes back.