​
Overview

The Terminal API provides persistent PTY-based terminals on the Allternit Factory pane engine. Each terminal session is a real shell process owned by the pane engine: it survives API restarts and UI reconnects, replays its scrollback (the last 2 MiB) to every new stream, and reports its exit code. A terminal is a pane like any Factory agent pane: it shows in the agent wall as term-<session_id>, and an agent started in it is detected there.

​
Base URL

All endpoints require a valid Bearer token in the Authorization header. See Authentication for details. The API reaches the pane engine over its Unix domain socket. It finds the socket with allternit-factory pane tty ensure, which also starts the pane engine when it isn’t running. ALLTERNIT_FACTORY_BIN names the binary (default: allternit-factory next to allternit-api, then on PATH; Allternit Desktop sets it), and ALLTERNIT_FACTORY_PANE_SOCKET names the socket directly. See allternit-mux (folded into the Factory) for the socket methods.

​
Endpoints

​
Create terminal

Request body:
All fields are optional. Defaults: Response:

​
Send input

Request body:
Response:

​
Resize terminal

Request body:
Response:

​
Close terminal

Response:

​
Stream output

The response is a text/event-stream. The server first replays the kept scrollback, then streams live output. Ping events are emitted every 15 seconds when no output is available. Example event:
When the shell exits, one exit event follows its last output. The stream then stays open with pings only, so an EventSource doesn’t reconnect and replay the scrollback again. Clients that don’t know the exit type ignore it.
exit_code is null when the pane engine couldn’t read it.

​
Error codes

Input and resize on a terminal whose shell already exited succeed and do nothing, as typing into a closed terminal does. Close always succeeds.