Terminal API

A project's terminal settings

Change a project's terminal settings

Admins and Owners only. allowProductionFileWrites lets the file browser upload files in the project's production environments (default off). Audited.

Host shell availability of a server

Whether the caller can open a shell on the server itself, and why not: the setting is off (the default), the caller's account has no two-factor authentication, or the server is offline. Owners and Admins with a signed-in session only; a token gets 403 session_required. **Shell.** GET /servers/{serverId}/shell/ws upgrades to a WebSocket with the protocol of the service terminal (see getServiceTerminal): the first message is JSON {"type":"open","cols":80,"rows":24,"confirmProduction":false} (no command: it is always the host's login shell). It answers 403 host_shell_disabled when the setting is off and 403 two_factor_required when the account has no 2FA, before the upgrade. A server that runs any service of a production environment needs confirmProduction: true. A person may hold 2 host shells; an idle session (no input for 15 minutes) is closed. Sessions are audited (server.shell.open, server.shell.close: who, server, duration); their I/O is never recorded.

Switch a server's host shell on or off

Owners and Admins only (signed-in session). Off by default. The host shell is a root shell on the server: switching it on is audited (server.shell.enable, server.shell.disable), and switching it off ends the sessions that are open.

List a directory inside a replica container

Lists the immediate children of an absolute path (directories first, at most 2000 entries). The listing reads the container's own filesystem through the Docker API; nothing on the host is reachable. Requires the Owner, Admin or Developer role.

Terminal and file browser availability

What the caller can do with the service's web terminal and file browser: its replicas, whether a terminal can be opened now, whether production needs a confirmation and whether the file browser may write. Requires the Owner, Admin or Developer role and deployments:write; a Viewer gets 403. **Terminal.** GET /services/{serviceId}/terminal/ws upgrades to a WebSocket (browser session cookie, same origin). The first client message is JSON {"type":"open","replica":0,"command":[…],"cols":80,"rows":24,"confirmProduction":false}; binary messages are terminal input/output; JSON {"type":"resize","cols":…,"rows":…} resizes and {"type":"close"} ends the session. The server answers opened, idle_warning, exit, error and closed JSON messages. Production services need confirmProduction: true. A principal may hold 3 sessions; an idle session (no input for 15 minutes) is closed. Sessions are audited (terminal.open, terminal.close); their I/O is never recorded. **Files.** GET /services/{serviceId}/files/content?replica=&path=&preview= streams a file (preview=true returns at most 1 MiB as text/plain); POST /services/{serviceId}/files/upload?replica=&path=<dir>&name=<file> stores the request body (Content-Length required, 50 MB at most). Uploads are refused in production unless an admin allowed writes for the project.