Terminal and one-off commands

Noust opens three things you used to need SSH for, and keeps a record of every one of them:

• A shell as an application, in the console: the account the application runs as, in its sandbox, in its directory, with its environment. For a Compose or container application, a shell in one of its containers.
• A command run once in an application, from the console or noust app exec: the same account, sandbox and environment, no shell, its output kept in a job's log.
• A root shell on the server itself, in the console, for administrators only, off until you turn it on.

A shell in the browser is an open door to an application's secrets. This page says what stands in front of the door, what is kept of everyone who goes through it, and how to change either.

• Using it
• The security model
• Recordings
• A command run once
• The server's own shell
• When the connection drops
• What the console's terminal does and refuses
• Configuration
• The ENS profile
• The API
• What it is not

Using it

In the console, an application's page has More actions > Terminal (/apps/<domain>/terminal), and Server > More actions > Open a terminal (/server/terminal) opens the server's. The page says what you are about to open and what is kept of it. Open terminal asks you to confirm it is you (sudo mode), then connects. The strip above the screen says where you are, as whom, when the session ends however busy it is, and how long it may sit idle.

Keys go to the program, as in any terminal, with three that are the console's:

The mouse wheel scrolls back as well, and double and triple clicks select a word and a line. On a full-screen program (an editor, a pager) the wheel sends arrow keys instead, because there is nothing to scroll back to.

Pasting into a program that asked for it is bracketed, so a pasted newline is text and not Enter. The text the program printed stays text: a pasted or printed escape sequence cannot make the console copy to your clipboard, open a link, or type for you (see What the console's terminal does and refuses).

Reading it without sight. The screen is drawn on a canvas, which a screen reader cannot read. Text view shows the same screen as text in a region the keyboard can scroll, and Read new output aloud announces new lines as they appear (off by default: a program that redraws the screen, such as an editor, would be read again each time).

Opening again. When a shell ends, the page says how ("The shell exited with status 3", "Closed: nothing was typed for 10 min") and Open a new terminal starts another with the same choices. Options chooses the shell (bash, sh, ash, zsh, dash; the server's default otherwise) and, for a stack that runs several services, the service.

From the command line, a command run once is noust app exec:

noust app exec shop.example.com -- rails runner 'puts User.count'
noust app exec --service worker shop.example.com -- ./bin/status

The program and its arguments follow --. They are given to the program as they are: -- echo 'a; b' prints a; b.

The security model

Every layer below is enforced on the server. The console only reflects them, which is why a request that skips the console meets all of them anyway.

Who may. apps.terminal opens a terminal or runs a command in an application: administrators and, inside their team, tenants. It is not an operator's permission, because a shell as the application reads the secrets the application has and changes what runs. A principal limited to some teams reaches only the applications of those teams. The server's shell needs server.terminal (administrators) and a principal that sees every team. On a fleet, each node also sets a ceiling for its central: an application's terminal needs noust fleet authorize --access admin, and the server's shell needs --allow-host-access as well.

Sudo mode. Asking for a terminal, and running a command, need sudo mode, like every destructive action: the console asks "Confirm it's you" and retries.

Approval. Opening a root shell on the server is one of the changes the four-eyes approvals cover (terminal.server). With approvals on, a second person approves the request before the ticket is issued.

A ticket, once. The call that asks for a terminal answers with a ticket: random, stored only as a hash, valid for 20 seconds, bound to the credential that asked (and to its address, as sessions are unless bind_session_to_ip is turned off), and spent the first time it is presented, even when that attempt is refused. A ticket read out of a proxy's log is worth nothing. The WebSocket then passes the same checks as every other: address, host, origin, the credential's own permission, the second-factor and usage-notice gates.

Whose shell it is. For an application on this server, the shell is a process of the application's own account (noust-app-<name>, or the account an older application already runs as), started in a transient systemd unit with the same confinement as its builds and hooks: the application's directory and .env, nothing of Noust's configuration, the store or root's home. The environment is the application's, plus TERM and the locale. For a Compose or container application, the shell is docker exec -it into one of its running containers, as the container's user; Noust adds no privilege the stack does not already give its service.

Bounded in time and number. A session ends after terminal.idle_minutes with nothing typed and after terminal.max_minutes in all; both are enforced by the process runner, not the browser, and the console warns a minute before. terminal.max_sessions and terminal.max_sessions_per_user bound how many are open. Whatever the console says, a session that no connection has attached to for a minute is ended.

Recorded, or not opened. A session cannot start without a recording. See below.

Everything is audited (the audit log's closed catalog):

Administrators can see the open sessions (GET /api/terminal/sessions) and end one (DELETE /api/terminal/sessions/{id}).

Recordings

Each session is recorded, input and output, in an asciicast v2 file, so any asciinema player plays it and nothing from Noust is needed to read it. Beside it, a small .json says how the session ended and holds the SHA-256 of the cast, which the terminal.end audit event repeats. The audit log is HMAC-chained, so a recording that no longer matches its digest was changed after the fact, and noust audit recording says so first.

They live in terminal-recordings/ beside the store, 0600, and are kept for retention.terminal_days (90 by default; under the ENS profile at least as long as the audit log).

• Bounded fairly. A recording takes at most terminal.recording.max_mb. Output has 80% of it and what was typed the rest, so a flood of output (yes, cat of a large file) fills its share and is replaced by one marker while what was typed keeps being recorded.
• Scrubbed. Every secret value Noust knows of the application (its marked variables, URLs with passwords) and Noust's own credentials are replaced by *** before anything is written, including a value split across two reads.
• Passwords are not recorded. What is typed while the program has echo off in line mode (a password prompt) is replaced by <hidden: the program asked for a secret>.
• What Noust does not know to be a secret is recorded as it was. A recording is an audit trail, not a vault: reading one needs audit.read, and is itself audited.

noust audit recordings                       # newest first; --app, --actor, --kind app|server
noust audit recording 20261006T091203Z-1f2e3d4c5b6a7988          # what was printed and typed
noust audit recording ID --no-input          # only what was printed
noust audit recording ID --format cast       # the asciicast, for a player

The text form removes the program's escape sequences, because printed as they are they would be obeyed by your own terminal.

A command run once

POST /api/apps/{domain}/exec, the console's Run a command once and noust app exec are one implementation:

• The command is an argument vector. A shell never sees it: a pipe, a redirection or $VAR reaches the program as text. The console splits what you type on spaces and quotes, shows you the list it will run, and says when an argument holds something a shell would have interpreted.
• It runs as the application's account in its sandbox, in its directory, with its environment. For a stack, in a container of the chosen service (docker exec, no TTY).
• From the console it is a job: its log is the output, scrubbed of the application's secrets, read while it runs and once more when it ends. At most 2 MiB are kept, with a marker where the rest was dropped. It never changes the application's state in the header, because a command is work done in an application, not something that happens to it.
• It stops after --timeout seconds (300 by default, at most terminal.exec.max_seconds). A command that exits with anything but 0, or that did not finish, is a failed job whose log says how, and noust app exec exits with the command's own status.
• In a container, stopping a command leaves the process Docker started running there: Docker has no way to signal it from outside. Use a timeout you can live with, and docker compose exec to look for what is left.

The server's own shell

It is root, with nothing in between: the shell an administrator gets over SSH. That is why it is a switch, off until you turn it on, and why the console says so on the page before opening it.

noust config set terminal.server.enabled true

The compliance control server_terminal can keep it off even then. A server where nobody chose a framework can have it refused on its own (noust compliance set server_terminal refused), and noust compliance set server_terminal allowed undoes that. A framework that holds the control (ENS, ISO 27001) keeps it off unless you also force it, which is put on record, or turn the framework off:

noust config set terminal.server.force_ens true

When it is off the page says exactly what keeps it off (the switch, the control, or the framework by name) and prints the command that changes it, and GET /api/terminal/status carries the same in server.reason and server.how, and as a sentence with a code in server.coded: terminal.server_off, terminal.server_control or terminal.server_framework, with the control, the frameworks and the command as its values. Opening a terminal that is off is refused with the same sentence. On a server that asks for a reason with every change the command carries --reason "<why>". Everything else in The security model applies, with the four-eyes approval on top.

When the connection drops

A WebSocket that drops does not end the shell. The server keeps it for 60 seconds, holding up to 256 KiB of what it printed meanwhile, and the console asks for a new ticket that resumes the same session, with the backoff every stream of the console uses. The page says "Reconnecting", and on return "Reconnected to the same shell" and, if the output outgrew the backlog, that some of it was lost. A reload within the minute finds the shell. After the minute the session is ended and recorded as such.

Closing the tab does not end the shell either: End session does. A session ends at once when the credential it was opened with stops being valid (the session was signed out, the account disabled).

What the console's terminal does and refuses

The console cannot use xterm.js: its content security policy forbids the <style> element the library injects. The terminal is its own, in panel/src/lib/terminal/ (the emulator) and panel/src/components/ui/terminal/ (the drawing on a <canvas>, set through the CSSOM).

It understands the subset of xterm's sequences real programs use: cursor movement and saving, erase, insert and delete of lines and characters, scroll regions, the alternate screen, tab stops, the 16, 256 and true colours of SGR with bold, dim, italic, underline, inverse, hidden and strike, the DEC line-drawing set, and the modes that change what is drawn or what keys send (application cursor keys, origin, auto-wrap, bracketed paste). Wide and combining characters take the cells they should.

It refuses, because each is a way for output to act on the person reading it:

• It never writes your clipboard (OSC 52) and never opens a link (OSC 8).
• It never reports the window's title or size in pixels back as input (CSI 21 t, CSI 14 t), the replies a hostile file once used to type into a shell.
• It answers only queries whose answer is fixed or a position: device status, cursor position and the two device attribute reports.
• It never sends mouse reports. A program that asks for the mouse gets none, and the console's own selection keeps working.
• A paste can never close its own bracket: an end-of-paste sequence inside the pasted text is removed.
• A sequence it does not know is ignored in bounded memory: an unterminated string is dropped after 4,096 characters, and a run of ignored bytes after 65,536.

The colours are the console's own tokens, read where the screen is drawn and read again when the theme changes, so a program's red is the console's failure red in both themes.

Configuration

A value that cannot be read falls back to its default: a limit is never the thing that fails closed into "no limit".

The ENS profile

Under security.profile: ens-medium the limits are capped and the server's shell is closed:

Every session is recorded in either profile, so the controls op.acc.6.4 (session limits) and op.exp.8 (records of activity) are met by the terminal as they are by the console.

The API

The socket speaks JSON text frames. The client sends input (data), resize (rows, cols), ping and close. The server sends ready (who, where, ends_in, whether this is a resumed session, whether output was lost), output (data), notice (a limit kind and the seconds left), ended (reason, exit_code), error (code, message) and pong. A console that cannot keep up makes the program wait instead of making the server hold the output in memory.

On a central, /ws/nodes/{node}/terminal and the node's routes are relayed over the node's tunnel: a central re-implements nothing a node does, and the node's own permissions and ceilings apply.

What it is not

• Not a replacement for SSH. It is a shell for the work an operator does through a console. A session is bounded in time, recorded, and ends when the console does.
• Not a boundary between applications that share an account, any more than the rest of Noust is: a shell as an application can do what the application can.
• Not tamper-proof against root on the machine. A recording's digest is in a chained log, which makes changing it detectable, not impossible; ship the audit log off the machine for that (audit.syslog, audit.journald).
• No file transfer, no port forwarding, no multiplexing. One session is one shell.