v49

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-01151216390.1 KB
Devbox
Devbox-ShellTools

Create or reconnect to a PTY session.

Looks up the PTY session identified by the path session_name and either reconnects to the existing session or creates it if it does not yet exist. The session_name is a client-chosen session identifier, not an opaque server-issued ID. It must be non-empty (1..=256 chars) and use only ASCII letters, digits, '-' and '_'. A newly created PTY session starts an interactive bash shell on the Devbox. Optional cols and rows query parameters apply an initial terminal size before any I/O; they must both be present and in the range 1..=1000 to take effect. The response returns a PtyConnectView containing connect_url (a server-relative path to the WebSocket data plane), idle_ttl_seconds (how long this session is retained after the last client disconnects), and the resulting cols/rows. The interactive terminal byte stream is exchanged over the WebSocket data plane and is not modeled in this OpenAPI contract; clients should connect to connect_url and exchange raw binary frames for terminal I/O. The single-attach contract is enforced when a client opens the WebSocket data plane, not on this bootstrap call: bootstrap always succeeds for a valid session_name, even if another client is currently attached. Rejection of a second concurrent attach happens at WebSocket upgrade time. If the active client disconnects, the session is preserved for the idle TTL so a later connect using the same session_name resumes the same shell. After the TTL expires, after an explicit close control action, or after the underlying Devbox lifecycle replaces the PTY process (such as through suspend/resume), a later request with the same session_name creates a fresh PTY session without the previous shell state.

get/pty/{session_name}

Path parameters

session_namestring required

The client-chosen PTY session name. Must be 1..=256 ASCII letters, digits, '-' and '_'. Reusing the same name reconnects to the same logical PTY session when it is still available.

Query parameters

colsinteger

Optional initial terminal width in character cells (1..=1000). Defaults to 80 when omitted. Applied only if both cols and rows are provided; otherwise ignored.

rowsinteger

Optional initial terminal height in character cells (1..=1000). Defaults to 24 when omitted. Applied only if both cols and rows are provided; otherwise ignored.

Response

OK

session_namestring
statusstring
protocol_versionstring
connect_urlstring
createdboolean required
attachedboolean required
colsinteger
rowsinteger
idle_ttl_secondsinteger
All 151 operations