> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Open an interactive terminal (PTY)

> Create a pseudo-terminal in a sandbox, send input, resize it, reconnect by pid, and kill it, for REPLs, debuggers and interactive command line tools.

A PTY (pseudo-terminal) is a virtual terminal interface that lets programs interact with a shell as if connected to a real terminal. The `sandbox.pty` module creates interactive terminal sessions that run commands, accept input, and can be resized while running. This fits REPLs and debuggers, interactive command line tools that prompt for input, and long-running processes that need monitoring.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

| Operation | Node.js | Python |
| - | - | - |
| Create | `sandbox.pty.create(opts)` | `sandbox.pty.create(size)` |
| Connect | `sandbox.pty.connect(pid, opts?)` | `sandbox.pty.connect(pid)` |
| Send input | `sandbox.pty.sendInput(pid, data)` | `sandbox.pty.send_stdin(pid, data)` |
| Resize | `sandbox.pty.resize(pid, size)` | `sandbox.pty.resize(pid, size)` |
| Kill | `sandbox.pty.kill(pid)` | `sandbox.pty.kill(pid)` |

> [!NOTE]
>
> A PTY is identified by its process ID (`pid`), returned from `create()`. Pass that `pid` to send input, resize, connect, and kill. Output is delivered to a callback as raw bytes.

## Use a PTY

**1. Create a PTY**

Create a PTY and receive its output through a callback. The call returns a handle whose `pid` identifies the PTY.

```python Python theme={null}
# PtySize takes keyword args cols / rows
pty = sandbox.pty.create(PtySize(cols=120, rows=30), cwd='/home/user', envs={'TERM': 'xterm-256color'})
print('PTY pid:', pty.pid)
```

```javascript Node.js theme={null}
const pty = await sandbox.pty.create({
  cols: 120,
  rows: 30,
  cwd: '/home/user',
  envs: { TERM: 'xterm-256color' },
  onData: (data) => {
    process.stdout.write(new TextDecoder().decode(data))
  },
})

console.log('PTY pid:', pty.pid)
```

**2. Send input**

Send input to a running PTY by its `pid`. The data is raw bytes.

```python Python theme={null}
sandbox.pty.send_stdin(pty.pid, b'echo hello\n')
```

```javascript Node.js theme={null}
const enc = new TextEncoder()
await sandbox.pty.sendInput(pty.pid, enc.encode('echo hello\n'))
```

**3. Resize the terminal**

Call `resize` when the terminal window changes size.

```python Python theme={null}
sandbox.pty.resize(pty.pid, PtySize(cols=150, rows=40))
```

```javascript Node.js theme={null}
await sandbox.pty.resize(pty.pid, { cols: 150, rows: 40 })
```

**4. Reconnect to the PTY**

Connect to a PTY that is already running by its `pid`. Running processes are listed by `sandbox.commands.list()`. The returned handle receives further output from the PTY.

```python Python theme={null}
handle = sandbox.pty.connect(pty.pid)
```

```javascript Node.js theme={null}
const handle = await sandbox.pty.connect(pty.pid, {
  onData: (data) => {
    process.stdout.write(new TextDecoder().decode(data))
  },
})
```

**5. Kill the PTY**

`kill` terminates the PTY with `SIGKILL`. It returns `true` if the PTY was killed, or `false` if no PTY with that `pid` was found.

```python Python theme={null}
killed = sandbox.pty.kill(pty.pid)
print('killed:', killed)
```

```javascript Node.js theme={null}
const killed = await sandbox.pty.kill(pty.pid)
console.log('killed:', killed)
```

### Full example

```python Python theme={null}
from ppio_sandbox import PPIO, PtySize

ppio = PPIO()
sandbox = ppio.sandbox.create()

output = []

def on_pty(data: bytes):
    output.append(data.decode('utf-8', errors='replace'))

# PtySize takes keyword args cols / rows
pty = sandbox.pty.create(PtySize(cols=120, rows=30), cwd='/home/user', envs={'TERM': 'xterm-256color'})
print('PTY pid:', pty.pid)

sandbox.pty.send_stdin(pty.pid, b'echo hello\n')

sandbox.pty.resize(pty.pid, PtySize(cols=150, rows=40))

handle = sandbox.pty.connect(pty.pid)

# Send exit and stream the output until the shell finishes
sandbox.pty.send_stdin(pty.pid, b'exit\n')
result = handle.wait(on_pty=on_pty)
print('exit code:', result.exit_code)
print(''.join(output))

killed = sandbox.pty.kill(pty.pid)
print('killed:', killed)

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

const pty = await sandbox.pty.create({
  cols: 120,
  rows: 30,
  cwd: '/home/user',
  envs: { TERM: 'xterm-256color' },
  onData: (data) => {
    process.stdout.write(new TextDecoder().decode(data))
  },
})

console.log('PTY pid:', pty.pid)

const enc = new TextEncoder()
await sandbox.pty.sendInput(pty.pid, enc.encode('echo hello\n'))

await sandbox.pty.resize(pty.pid, { cols: 150, rows: 40 })

const handle = await sandbox.pty.connect(pty.pid, {
  onData: (data) => {
    process.stdout.write(new TextDecoder().decode(data))
  },
})

await sandbox.pty.sendInput(pty.pid, enc.encode('exit\n'))
await handle.wait()

const killed = await sandbox.pty.kill(pty.pid)
console.log('killed:', killed)

await sandbox.kill()
```

## PTY options

> [tab] Python
>
> **size** `PtySize`
>
> Terminal dimensions. Pass `cols` and `rows` as keyword arguments.
>
> **properties**
>
> **cols** `int`
>
> Number of columns.
>
> **rows** `int`
>
> Number of rows.
>
> **user** `string`
>
> User to run the PTY as. Optional.
>
> **cwd** `string`
>
> Working directory. Optional.
>
> **envs** `dict`
>
> Environment variables. `TERM`, `LANG` and `LC_ALL` are defaulted. Optional.
>
> **timeout** `number` (default: 60)
>
> PTY timeout, in seconds.
>
> In Python, output is delivered through `wait(on_pty=...)` instead of an `onData` option.

> [tab] Node.js
>
> **cols** `number`
>
> Terminal width in columns.
>
> **rows** `number`
>
> Terminal height in rows.
>
> **onData** `function`
>
> Callback for PTY output, delivered as raw bytes.
>
> **user** `string`
>
> User to run the PTY as. Optional.
>
> **cwd** `string`
>
> Working directory. Optional.
>
> **envs** `object`
>
> Environment variables. `TERM`, `LANG` and `LC_ALL` are defaulted. Optional.
>
> **timeoutMs** `number` (default: 60000)
>
> PTY timeout, in milliseconds.

## Interactive example

Create a PTY, send an interactive command that prompts for input, then wait for it to finish and read the exit code. In Python, `wait(on_pty=...)` streams output to the callback and returns the result.

```python Python theme={null}
from ppio_sandbox import PPIO, PtySize

ppio = PPIO()
sandbox = ppio.sandbox.create()

output = []

def on_pty(data: bytes):
    output.append(data.decode('utf-8', errors='replace'))

terminal = sandbox.pty.create(PtySize(cols=80, rows=24), envs={'ABC': '123'}, cwd='/')

# Send a command and exit
sandbox.pty.send_stdin(terminal.pid, b'echo $ABC\nexit\n')

# Stream output and wait for completion
result = terminal.wait(on_pty=on_pty)
print('exit code:', result.exit_code)
print(''.join(output))

sandbox.kill()
```


## Related topics

- [ppio sandbox connect](https://docs.ppio.ai/sandbox/cli/connect.md)
- [Connect a sandbox to a VPN with OpenVPN](https://docs.ppio.ai/sandbox/openvpn.md)
- [Manage sandboxes in the PPIO console](https://docs.ppio.ai/sandbox/console.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.