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

# List sandbox processes

> List the processes in a running sandbox, or the last stored sample of a stopped one.



## OpenAPI

````yaml openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/processes
openapi: 3.1.0
info:
  title: Boat Public API v1
  version: 1.0.0
  description: >
    Public JSON API for creating, operating, prompting, observing, and exposing
    sandboxes from backend services, CI jobs, hosted workers, and Boat
    automation products.


    The v1 reference intentionally documents the developer integration surface
    only. Dashboard billing actions are not part of v1.
servers:
  - url: https://boat.dev/api/v1
security:
  - BoatBearerAuth: []
tags:
  - name: Boat
    description: >-
      Unified Boat account, setup, lifecycle, prompting, event history, desktop
      access, and SSH operations.
paths:
  /sandboxes/{sandboxId}/processes:
    get:
      tags:
        - Boat
      summary: List the processes in a sandbox
      description: >-
        A running sandbox: every user-space process, read now, busiest first. A
        stopped sandbox: the last sample kept (`live: false`).
      operationId: processes
      parameters:
        - $ref: '#/components/parameters/SandboxId'
      responses:
        '200':
          description: The processes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    SandboxId:
      name: sandboxId
      in: path
      required: true
      schema:
        type: string
        pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$
      description: Public Sandbox id returned by create/list/get sandbox calls.
  schemas:
    ProcessListResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessBase'
        - type: object
          required:
            - live
            - sampledAt
            - processes
            - total
          properties:
            type:
              type: string
              const: process.list
            live:
              type: boolean
              description: >-
                True: read from the running sandbox now. False: the sandbox is
                stopped (or its agent is not upgraded yet), and this is the last
                sample kept (top 12 processes, every 30 s, 7 days).
            sampledAt:
              type:
                - string
                - 'null'
              format: date-time
            total:
              type: integer
              description: Processes on the sandbox. The list holds at most 500
              busiest first.: null
            processes:
              type: array
              items:
                $ref: '#/components/schemas/SandboxProcess'
    SuccessBase:
      type: object
      required:
        - ok
        - type
      properties:
        ok:
          type: boolean
          examples:
            - true
        type:
          type: string
          description: Stable success envelope discriminator added by v1.
    SandboxProcess:
      type: object
      required:
        - pid
        - command
      properties:
        pid:
          type: integer
        parentPid:
          type: integer
          description: Live list only.
        user:
          type: string
          description: Live list only.
        cpuPercent:
          type: number
        memoryMB:
          type: number
          description: Resident memory.
        startedAt:
          type: string
          format: date-time
          description: Live list only.
        command:
          type: string
          description: >-
            The full command line (first 1000 characters; 120 in a stored
            sample).
        commandId:
          type:
            - string
            - 'null'
          description: >-
            Live list: the history record holding this process's output, when it
            has one.
    ErrorEnvelope:
      type: object
      required:
        - ok
        - type
        - status
        - code
        - message
        - error
        - requestId
      properties:
        ok:
          type: boolean
          examples:
            - false
        type:
          type: string
          examples:
            - sandbox.error
        status:
          type: integer
          examples:
            - 409
        code:
          type: string
          examples:
            - provider_not_configured
        message:
          type: string
          examples:
            - Prompting is locked until Codex is configured on the Agents page.
        requestId:
          type: string
          examples:
            - req_01HX...
        error:
          type: object
          required:
            - code
            - message
            - status
          properties:
            code:
              type: string
            message:
              type: string
            status:
              type: integer
            details:
              type: object
              additionalProperties: true
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            unauthorized:
              value:
                ok: false
                type: sandbox.error
                status: 401
                code: unauthorized
                message: Unauthorized
                error:
                  code: unauthorized
                  message: Unauthorized
                  status: 401
                requestId: req_01HX...
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    BoatBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sandbox_api_key
      description: >-
        Boat bearer token in the form `boat_...`. Service API keys authenticate
        sandbox operations.

````

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