PTY Sessions

Create PTY Session

POST /v1/sandboxes/:id/pty

Create a new PTY (pseudo-terminal) session for interactive programs like Python REPL, vim, or shell sessions.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The full sandbox ID

Request Body

Parameter	Type	Required	Description
`command`	string	Yes	Command to run (e.g., `bash`, `python3`, `vim`)
`cols`	number	No	Terminal width in columns. Defaults to 80.
`rows`	number	No	Terminal height in rows. Defaults to 24.

Example

curl -X POST https://api.conway.tech/v1/sandboxes/abc123def456/pty \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python3",
    "cols": 120,
    "rows": 40
  }'

const response = await fetch(
  "https://api.conway.tech/v1/sandboxes/abc123def456/pty",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      command: "python3",
      cols: 120,
      rows: 40,
    }),
  }
);

Response

{
  "session_id": "pty_789xyz",
  "sandbox_id": "abc123def456",
  "command": "python3",
  "cols": 120,
  "rows": 40,
  "state": "running",
  "created_at": "2026-01-30T12:00:00Z"
}

Use Cases

Interactive REPLs: Python, Node.js, Ruby interpreters
Text editors: vim, nano, emacs
Interactive CLIs: AWS CLI, kubectl, docker
Shell sessions: Long-running bash sessions with state

Write to PTY

POST /v1/sandboxes/:id/pty/:sessionId/write

Send input to a PTY session.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The full sandbox ID
`sessionId`	string	Yes	The PTY session ID

Request Body

Parameter	Type	Required	Description
`input`	string	Yes	Input to send. Use `\n` for Enter, `\x03` for Ctrl+C.

Example

curl -X POST https://api.conway.tech/v1/sandboxes/abc123def456/pty/pty_789xyz/write \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "print(\"Hello, World!\")\n"
  }'

const response = await fetch(
  "https://api.conway.tech/v1/sandboxes/abc123def456/pty/pty_789xyz/write",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      input: 'print("Hello, World!")\n',
    }),
  }
);

Response

{
  "success": true,
  "bytes_written": 24,
  "session_id": "pty_789xyz"
}

Special Characters

Character	Escape Sequence	Description
Enter	`\n`	Submit command
Tab	`\t`	Tab completion
Ctrl+C	`\x03`	Interrupt/cancel
Ctrl+D	`\x04`	EOF/exit
Ctrl+Z	`\x1a`	Suspend process
Arrow Up	`\x1b[A`	Previous command
Arrow Down	`\x1b[B`	Next command

Read from PTY

GET /v1/sandboxes/:id/pty/:sessionId/read

Read output from a PTY session.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The full sandbox ID
`sessionId`	string	Yes	The PTY session ID

Query Parameters

Parameter	Type	Required	Description
`full`	boolean	No	If `true`, return full scrollback buffer. Default: `false` (current screen only).

Example

curl "https://api.conway.tech/v1/sandboxes/abc123def456/pty/pty_789xyz/read?full=false" \
  -H "Authorization: Bearer your-api-key"

const response = await fetch(
  "https://api.conway.tech/v1/sandboxes/abc123def456/pty/pty_789xyz/read?full=false",
  {
    headers: { Authorization: "Bearer your-api-key" },
  }
);

Response

{
  "output": "Python 3.11.0 (main, Oct 24 2022, 18:26:48)\n>>> print(\"Hello, World!\")\nHello, World!\n>>> ",
  "state": "running",
  "session_id": "pty_789xyz",
  "cols": 120,
  "rows": 40
}

Tips

Poll this endpoint periodically to get updated output
Use full=true to retrieve scrollback history for long sessions
Check state to detect if the process has exited

Resize PTY

POST /v1/sandboxes/:id/pty/:sessionId/resize

Resize a PTY session's terminal dimensions.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The full sandbox ID
`sessionId`	string	Yes	The PTY session ID

Request Body

Parameter	Type	Required	Description
`cols`	number	Yes	New terminal width in columns
`rows`	number	Yes	New terminal height in rows

Example

curl -X POST https://api.conway.tech/v1/sandboxes/abc123def456/pty/pty_789xyz/resize \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "cols": 200,
    "rows": 50
  }'

const response = await fetch(
  "https://api.conway.tech/v1/sandboxes/abc123def456/pty/pty_789xyz/resize",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ cols: 200, rows: 50 }),
  }
);

Response

{
  "success": true,
  "session_id": "pty_789xyz",
  "cols": 200,
  "rows": 50
}

Close PTY Session

DELETE /v1/sandboxes/:id/pty/:sessionId

Close a PTY session and terminate the running process.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The full sandbox ID
`sessionId`	string	Yes	The PTY session ID to close

Example

curl -X DELETE https://api.conway.tech/v1/sandboxes/abc123def456/pty/pty_789xyz \
  -H "Authorization: Bearer your-api-key"

await fetch(
  "https://api.conway.tech/v1/sandboxes/abc123def456/pty/pty_789xyz",
  {
    method: "DELETE",
    headers: { Authorization: "Bearer your-api-key" },
  }
);

Response

{
  "success": true,
  "session_id": "pty_789xyz",
  "state": "exited"
}

List PTY Sessions

GET /v1/sandboxes/:id/pty

List all active PTY sessions for a sandbox.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The full sandbox ID

Example

curl https://api.conway.tech/v1/sandboxes/abc123def456/pty \
  -H "Authorization: Bearer your-api-key"

const response = await fetch(
  "https://api.conway.tech/v1/sandboxes/abc123def456/pty",
  {
    headers: { Authorization: "Bearer your-api-key" },
  }
);

Response

{
  "sandbox_id": "abc123def456",
  "sessions": [
    {
      "session_id": "pty_789xyz",
      "command": "python3",
      "state": "running",
      "cols": 120,
      "rows": 40,
      "created_at": "2026-01-30T12:00:00Z"
    },
    {
      "session_id": "pty_abc123",
      "command": "bash",
      "state": "running",
      "cols": 80,
      "rows": 24,
      "created_at": "2026-01-30T12:05:00Z"
    }
  ],
  "total": 2
}

On this page