---
title: "Create or reconnect to a PTY session."
method: GET
path: "/pty/{session_name}"
tags: ["Devbox", "Devbox-ShellTools"]
---

# Create or reconnect to a PTY session.

`GET /pty/{session_name}`

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.

## Path parameters

- `session_name` string, required

## Query parameters

- `cols` integer
- `rows` integer

## Response `200`

OK

- PtyConnectView
  - `session_name` string
  - `status` string
  - `protocol_version` string
  - `connect_url` string
  - `created` boolean, required
  - `attached` boolean, required
  - `cols` integer
  - `rows` integer
  - `idle_ttl_seconds` integer

## Other responses

- `400` — Malformed session_name (alphabet or length out of range).
- `503` — PTY session could not be spawned (host resource exhaustion).

---

[API](https://skmtc.net/runloopai/apis/runloop-api.md) · [All operations](https://skmtc.net/runloopai/apis/runloop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/runloopai/runloop-api/versions/ef553a04de89/schema)