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

# Send a control command to a PTY session.

> Applies a PTY control operation to an existing session. The action field selects the operation; the other fields in PtyControlParams are interpreted only when they are relevant to the chosen action.

resize: cols and rows are required and must each be in 1..=1000. A 0 or out-of-range value returns 400. The new winsize is applied to the PTY master and the kernel delivers SIGWINCH to the foreground process group.

signal: signal is the POSIX signal name (for example 'SIGTERM', 'SIGHUP', 'SIGINT', 'SIGUSR1'). Unknown signal names return 400. The signal is delivered to the slave's foreground process group via killpg(2). If the shell has already exited and there is no foreground process group, returns 400.

close: terminates the session. Sends SIGHUP to the foreground process group (best-effort; ignored if the shell has already exited) and drops the session from the server's session cache. A subsequent connect with the same session_name will create a fresh PTY session.



## OpenAPI

````yaml /openapi-specs/stainless-processed-openapi.json post /pty/{session_name}/control
openapi: 3.1.0
info:
  title: RunLoop API
  version: '0.1'
  description: >-
    The RunLoop API spec that allows you to host lambda functions and Devboxes
    to enable scaled long running ai workflows.
  contact:
    name: Runloop AI Support
    url: https://runloop.ai
    email: support@runloop.ai
servers:
  - url: https://api.runloop.ai
    description: Runloop API
    variables: {}
security:
  - bearerAuth: []
tags:
  - name: Benchmark
  - name: Blueprint
  - name: Blueprint-Lifecycle
  - name: Blueprint-ObservabilityTools
  - name: Devbox
  - name: Devbox-FileTools
  - name: Devbox-Lifecycle
  - name: Devbox-NetworkTools
  - name: Devbox-ObservabilityTools
  - name: Devbox-PersistenceTools
  - name: Devbox-ShellTools
  - name: Scenario
  - name: ScenarioScorer
  - name: accounts
  - name: agents
  - name: apikeys
  - name: axons
  - name: executions
  - name: gateway-configs
  - name: mcp-configs
  - name: network-policies
  - name: objects
  - name: restricted_keys
  - name: secrets
  - name: streaming
paths:
  /pty/{session_name}/control:
    post:
      tags:
        - Devbox
        - Devbox-ShellTools
      summary: Send a control command to a PTY session.
      description: >-
        Applies a PTY control operation to an existing session. The action field
        selects the operation; the other fields in PtyControlParams are
        interpreted only when they are relevant to the chosen action.


        resize: cols and rows are required and must each be in 1..=1000. A 0 or
        out-of-range value returns 400. The new winsize is applied to the PTY
        master and the kernel delivers SIGWINCH to the foreground process group.


        signal: signal is the POSIX signal name (for example 'SIGTERM',
        'SIGHUP', 'SIGINT', 'SIGUSR1'). Unknown signal names return 400. The
        signal is delivered to the slave's foreground process group via
        killpg(2). If the shell has already exited and there is no foreground
        process group, returns 400.


        close: terminates the session. Sends SIGHUP to the foreground process
        group (best-effort; ignored if the shell has already exited) and drops
        the session from the server's session cache. A subsequent connect with
        the same session_name will create a fresh PTY session.
      operationId: controlDevboxPtySession
      parameters:
        - name: session_name
          in: path
          description: >-
            The client-chosen PTY session name. Must be 1..=256 ASCII letters,
            digits, '-' and '_'.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PtyControlParameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PtyControlResultView'
        '400':
          description: >-
            Invalid action parameters: out-of-range cols/rows on resize, unknown
            signal name on signal, or no foreground process group on signal.
        '404':
          description: PTY session not found.
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Runloop from '@runloop/api-client';


            const client = new Runloop({
              bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted
            });


            const ptyControlResultView = await
            client.pty.control('session_name');


            console.log(ptyControlResultView.session_name);
        - lang: Python
          source: |-
            import os
            from runloop_api_client import Runloop

            client = Runloop(
                bearer_token=os.environ.get("RUNLOOP_API_KEY"),  # This is the default and can be omitted
            )
            pty_control_result_view = client.pty.control(
                session_name="session_name",
            )
            print(pty_control_result_view.session_name)
components:
  schemas:
    PtyControlParameters:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/PtyControlAction'
        cols:
          type: integer
          format: int32
        rows:
          type: integer
          format: int32
        signal:
          type: string
    PtyControlResultView:
      type: object
      properties:
        session_name:
          type: string
        status:
          type: string
    PtyControlAction:
      type: string
      enum:
        - resize
        - signal
        - close
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````