> ## Documentation Index > Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi-specs/stainless-processed-openapi.json get /pty/{session_name} openapi: 3.1.0 info: title: RunLoop API version: '0.1' description: >- The RunLoop API spec that allows you to host lambda functions and Devboxes to enable scaled long running ai workflows. contact: name: Runloop AI Support url: https://runloop.ai email: support@runloop.ai servers: - url: https://api.runloop.ai description: Runloop API variables: {} security: - bearerAuth: [] tags: - name: Benchmark - name: Blueprint - name: Blueprint-Lifecycle - name: Blueprint-ObservabilityTools - name: Devbox - name: Devbox-FileTools - name: Devbox-Lifecycle - name: Devbox-NetworkTools - name: Devbox-ObservabilityTools - name: Devbox-PersistenceTools - name: Devbox-ShellTools - name: Scenario - name: ScenarioScorer - name: accounts - name: agents - name: apikeys - name: axons - name: executions - name: gateway-configs - name: mcp-configs - name: network-policies - name: objects - name: restricted_keys - name: secrets - name: streaming paths: /pty/{session_name}: get: tags: - Devbox - Devbox-ShellTools summary: Create or reconnect to a PTY session. description: >- 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. operationId: connectDevboxPtySession parameters: - name: session_name in: path description: >- 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. required: true schema: type: string - name: cols in: query description: >- 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. schema: type: integer format: int32 - name: rows in: query description: >- 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. schema: type: integer format: int32 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PtyConnectView' '400': description: Malformed session_name (alphabet or length out of range). '503': description: PTY session could not be spawned (host resource exhaustion). x-codeSamples: - lang: JavaScript source: |- import Runloop from '@runloop/api-client'; const client = new Runloop({ bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted }); const ptyConnectView = await client.pty.connect('session_name'); console.log(ptyConnectView.idle_ttl_seconds); - lang: Python source: |- import os from runloop_api_client import Runloop client = Runloop( bearer_token=os.environ.get("RUNLOOP_API_KEY"), # This is the default and can be omitted ) pty_connect_view = client.pty.connect( session_name="session_name", ) print(pty_connect_view.idle_ttl_seconds) components: schemas: PtyConnectView: type: object properties: session_name: type: string status: type: string protocol_version: type: string connect_url: type: string created: type: boolean attached: type: boolean cols: type: integer format: int32 rows: type: integer format: int32 idle_ttl_seconds: type: integer format: int64 required: - created - attached securitySchemes: bearerAuth: scheme: bearer type: http ````