> ## 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.

# Create PTY Session

> Start a pseudo-terminal session inside a runtime

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

Allocates a pseudo-terminal in the runtime and launches a shell on it. Every argument is
optional; omitted values use the execution plane defaults (`/bin/bash` in `/workspace` at
80x24).

The session keeps running after this call returns and after the client disconnects.

<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(
      shell="/bin/bash",
      working_dir="/workspace",
      environment={"TERM": "xterm-256color"},
      cols=120,
      rows=40,
  )

  print(session.session_id, session.pid, session.status)
  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({
    shell: '/bin/bash',
    workingDir: '/workspace',
    environment: { TERM: 'xterm-256color' },
    cols: 120,
    rows: 40,
  });

  console.log(session.sessionId, session.pid, session.status);
  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime pty create "$RT" --shell /bin/bash --workdir /workspace --cols 120 --rows 40
  ```

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

## Parameters

| Parameter     | Type    | Required | Description                                                    |
| ------------- | ------- | -------- | -------------------------------------------------------------- |
| `shell`       | string  | No       | Shell to launch. Must be one of the runtime's permitted shells |
| `args`        | array   | No       | Arguments passed to the shell                                  |
| `working_dir` | string  | No       | Initial working directory                                      |
| `environment` | object  | No       | Extra environment variables, merged over the runtime's own     |
| `cols`        | integer | No       | Terminal width in columns                                      |
| `rows`        | integer | No       | Terminal height in rows                                        |

## Response

Returns a [`PtySession`](/documentation/agentruntime/pty-sessions/overview#session-object-ptysession).

## Notes

* Set `cols` and `rows` to match the surface you will render the output on. Programs that
  format for the terminal width read them at start up, so getting the geometry right at
  creation time avoids a reflow.
* A runtime allows 8 concurrent sessions. If you create sessions per task, kill them when
  the task finishes.
* Setting `TERM` to `xterm-256color` enables colour output from most tools. Leave it unset
  if you would rather parse plain text without escape sequences.