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

# Manage PTY Sessions

> List, inspect, resize, signal and kill PTY sessions

## List sessions

`GET /v1/agents/runtime/{runtime_id}/pty`

Returns every PTY session belonging to the runtime, including sessions that have exited but
not yet been reaped.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from gravixlayer import GravixLayer

  client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
  sandbox = client.runtime.create()  # defaults to template="base-small"

  for session in sandbox.pty.list():
      print(session.session_id, session.status, session.pid, session.shell)

  sandbox.kill()
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { GravixLayer } from 'gravixlayer';

  const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"

  for (const session of await sandbox.pty.list()) {
    console.log(session.sessionId, session.status, session.pid, session.shell);
  }

  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime pty ls "$RT"
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pty" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
  ```
</CodeGroup>

Responds with `{"sessions": [PtySession, ...]}`.

***

## Describe a session

`GET /v1/agents/runtime/{runtime_id}/pty/{session_id}`

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from gravixlayer import GravixLayer

  client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
  sandbox = client.runtime.create()  # defaults to template="base-small"
  session = sandbox.pty.create()

  info = sandbox.pty.get(session.session_id)
  print(info.status, info.exit_code, info.cols, info.rows)

  sandbox.kill()
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { GravixLayer } from 'gravixlayer';

  const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"
  const session = await sandbox.pty.create();

  const info = await sandbox.pty.get(session.sessionId);
  console.log(info.status, info.exitCode, info.cols, info.rows);

  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime pty get "$RT" "$SID"
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pty/$SID" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
  ```
</CodeGroup>

Returns a [`PtySession`](/documentation/agentruntime/pty-sessions/overview#session-object-ptysession).
Poll this when you want to know whether a session has exited without holding a stream open.

***

## Resize

`POST /v1/agents/runtime/{runtime_id}/pty/{session_id}/resize`

Changes the terminal geometry and delivers `SIGWINCH` to the foreground job, so full screen
programs redraw at the new size.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from gravixlayer import GravixLayer

  client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
  sandbox = client.runtime.create()  # defaults to template="base-small"
  session = sandbox.pty.create()

  sandbox.pty.resize(session.session_id, cols=200, rows=50)
  sandbox.kill()
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { GravixLayer } from 'gravixlayer';

  const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"
  const session = await sandbox.pty.create();

  await sandbox.pty.resize(session.sessionId, 200, 50);
  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime pty resize "$RT" "$SID" --cols 200 --rows 50
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pty/$SID/resize" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"cols": 200, "rows": 50}'
  ```
</CodeGroup>

| Parameter | Type    | Required | Description                                 |
| --------- | ------- | -------- | ------------------------------------------- |
| `cols`    | integer | Yes      | Terminal width in columns; must be positive |
| `rows`    | integer | Yes      | Terminal height in rows; must be positive   |

***

## Send a signal

`POST /v1/agents/runtime/{runtime_id}/pty/{session_id}/signal`

Signals the session's process directly.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from gravixlayer import GravixLayer

  client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
  sandbox = client.runtime.create()  # defaults to template="base-small"
  session = sandbox.pty.create()

  sandbox.pty.send_signal(session.session_id, "INT")
  sandbox.kill()
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { GravixLayer } from 'gravixlayer';

  const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"
  const session = await sandbox.pty.create();

  await sandbox.pty.sendSignal(session.sessionId, 'INT');
  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime pty signal "$RT" "$SID" INT
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pty/$SID/signal" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"signal": "INT"}'
  ```
</CodeGroup>

| Signal | Effect                                           |
| ------ | ------------------------------------------------ |
| `INT`  | Interrupt, as Ctrl-C would                       |
| `TERM` | Polite termination request                       |
| `KILL` | Immediate, uncatchable termination               |
| `HUP`  | Hangup, as a disconnected terminal would deliver |

Names are accepted with or without the `SIG` prefix. Only these four signals are permitted.

<Note>
  Writing `\x03` with [send input](/documentation/agentruntime/pty-sessions/send-input) goes
  through the terminal's line discipline and interrupts the **foreground job**, leaving the
  shell running. This endpoint signals the **session process** itself. Use input for
  Ctrl-C semantics and this endpoint when you want to act on the session regardless of what
  is running in it.
</Note>

***

## Kill a session

`DELETE /v1/agents/runtime/{runtime_id}/pty/{session_id}`

Terminates the session and releases its terminal, scrollback buffer and slot in the
per-runtime session limit.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from gravixlayer import GravixLayer

  client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
  sandbox = client.runtime.create()  # defaults to template="base-small"
  session = sandbox.pty.create()

  sandbox.pty.kill(session.session_id)
  sandbox.kill()
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { GravixLayer } from 'gravixlayer';

  const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"
  const session = await sandbox.pty.create();

  await sandbox.pty.kill(session.sessionId);
  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime pty kill "$RT" "$SID"
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X DELETE "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pty/$SID" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
  ```
</CodeGroup>

Sessions are also killed automatically when the runtime is stopped or deleted, so you do not
need to clean up before tearing a runtime down. Kill sessions explicitly when a runtime is
long lived and you are creating a session per task.