Terminal module reference

Actions

14 actions, callable from the panel, the command palette and the API as POST /api/v1/a/<id>. Internal actions used between modules are not listed.

Action	What it does	Risk	Preview
`terminal.session.open`	Open a terminal	medium	No dry run
`terminal.root.open`	Open a root terminal	critical
`terminal.session.list`	List terminal sessions (read)	low	No dry run
`terminal.session.kill`	Kill a terminal session	medium	No dry run
`terminal.recording.list`	List recordings (read)	low	No dry run
`terminal.recording.get`	Read part of a recording (read)	low	No dry run
`terminal.recording.delete`	Delete a recording	high
`terminal.session.resume`	Re-attach to a running terminal	medium	No dry run
`terminal.container.open`	Open a shell inside a container	medium	No dry run
`terminal.snippet.list`	List your saved commands (read)	low	No dry run
`terminal.snippet.set`	Save a command	low	No dry run
`terminal.snippet.delete`	Delete a saved command	low	No dry run
`terminal.prefs.get`	Your terminal display settings (read)	low	No dry run
`terminal.prefs.set`	Change your terminal display settings	low	No dry run

Permissions and limits

Permissions

terminal.use Open a terminal in an account
terminal.view See terminal sessions and recordings
terminal.manage Kill sessions
terminal.root Open a root terminal on a server
terminal.recording.manage Delete recordings
terminal.snippet.manage Keep your own saved commands and display settings
terminal.container Be handed a shell inside a container by the containers module

Plan limits

terminal.sessions Concurrent terminal sessions

Engineering notes

Generated from modules/terminal/docs.md at build f3a3c074. These are the notes the engineers keep next to the code: precise, technical, and honest about what is not done yet.

PTY on the account's server as the account Unix user (credential drop, in the account's cgroup slice — the agent creates a conservative rc-acct-<u>.slice with TasksMax 1024 if the limits module has not made one), env TERM=xterm-256color, UTF-8. No action runs a command (AC-terminal-21); the only entry is an interactive PTY.

Flow: terminal.session.open (limit terminal.sessions, sweep of dead sessions) -> agent terminal.pty.open -> single-use ticket (random 32 bytes, only sha256 stored, 30 s) -> gateway redeems with internal terminal.ticket.redeem (atomic UPDATE ... WHERE used_at IS NULL, caller must be the opener) -> stream on NATS rc.pty.<node>.<session>.{in,out,ctl} (node-scoped: the bus lets each agent touch only its own sessions) with credit-based flow control (initial 256 KiB, 16 KiB frames), reattach replays the last 256 KiB, idle warning at -60 s then close, max duration, asciinema v3 recording (output only unless RecordInput) to /var/lib/respirecloud/recordings/<session>.cast (0600). Closing kills the shell and every process left in its session (job-control children, fork bombs) but not setsid daemons (tmux). Root terminal: admin kind, no impersonation, fresh step-up, always recorded, audited with the reason.

Settings (module settings JSON): record_users (default false), idle_minutes 30, session_max_minutes 480. Next: shadow/live view, snippets, bubblewrap cage, recording encryption + storage upload, retention sweeper, package/account/sub-user disable hooks, kill on suspension.