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

# Terminals

> A terminal is a shell or command the host starts in a session's workspace as the agent's Unix user, over WebSocket only

`opc shell` is a client for terminals.

## Access

| Item | Rule |
| - | - |
| Caller | The session's owner or an admin, with the `terminals` scope. Anyone else: `403 forbidden` with `reason: "terminal_owner_only"` |
| Process user | The agent's Unix user |
| Environment | `HOME`, `USER`, `LOGNAME`, `SHELL`, `PATH`, `LANG`, `TERM`. No session secrets |

## Open

```json theme={null}
{"jsonrpc":"2.0","id":8,"method":"terminals.open","params":{"sessionId":"cs_0123456789abcdef","cols":120,"rows":40}}
```

```json theme={null}
{"jsonrpc":"2.0","id":8,"result":{"terminal":{"id":"tm_...","channel":1,"stderrChannel":null}}}
```

| Param | Meaning |
| - | - |
| `tty` | Default true: a pseudo-terminal; `cols` and `rows` are required. False: plain pipes, with standard error on its own channel, `stderrChannel` |
| `cols`, `rows` | 1 to 1,000 |
| `command` | A command to run instead of an interactive shell, up to 10,000 characters |
| `term` | The `TERM` value, up to 64 characters |

| Error | Cause |
| - | - |
| `409 too_many_terminals` | The session already holds 8 terminals, across all connections |

A session with an open terminal is not suspended for being idle. The journal records `terminal.opened` and `terminal.closed` events.

## Data frames

A binary WebSocket frame is a 4-byte big-endian channel number, then the data.

| Direction | Channel | Limit |
| - | - | - |
| Client to server (input) | `channel` | 1 MiB per second per terminal. The server drops input over the limit, and the next request on the connection reports `rate_limited` |
| Server to client (output) | `channel`, and `stderrChannel` when there is one | 64 KiB per frame, channel number included |

## Resize, end input, close

Each method takes the `terminalId`.

| Method | Effect |
| - | - |
| `terminals.resize` | Sets `cols` and `rows` |
| `terminals.eof` | Closes the process's standard input |
| `terminals.close` | Hangs up: `SIGHUP` to the process group, `SIGKILL` 5 seconds later |

A terminal belongs to the connection that opened it.

| Case | Result |
| - | - |
| Its id used on another connection | `404 terminal_not_found` |
| The connection closes | Every terminal it opened closes |
| The process exits | The server sends `terminal.exited` |

```json theme={null}
{"jsonrpc":"2.0","method":"terminal.exited","params":{"terminalId":"tm_...","exitCode":0,"signal":null}}
```


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