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

# Run a command in a sandbox

> Runs a shell command in a running sandbox started through this API or the CostGraph MCP tools and returns its exit code and output. stdout and stderr hold at most 256 KiB each, and truncated is true when either was cut. timeout_ms limits the command, up to 55000; background true starts the command and returns at once. A sandbox the provider has ended is recorded as stopped and answers 404.



## OpenAPI

````yaml /api-reference/costgraph/openapi.json post /api/v1/tenant/sandboxes/{provider}/{sandbox_id}/exec
openapi: 3.0.0
info:
  description: Read and manage your CostGraph organization, spend, alerts, and settings.
  title: CostGraph API
  contact: {}
  version: '1.0'
servers:
  - url: https://api.costgraph.ai
security: []
tags:
  - name: ai
    x-group: AI
  - name: ai-serving
    x-group: AI serving
  - name: anomalies
    x-group: Anomalies
  - name: auth
    x-group: Auth
  - name: billing
    x-group: Billing
  - name: billing-export
    x-group: Billing export
  - name: budgets
    x-group: Budgets
  - name: ci
    x-group: CI
  - name: compute-recommendations
    x-group: Compute recommendations
  - name: config
    x-group: Config
  - name: context-graph
    x-group: Context graph
  - name: cost
    x-group: Cost
  - name: gpus
    x-group: GPUs
  - name: graphai
    x-group: Graph AI
  - name: integrations
    x-group: Integrations
  - name: invitations
    x-group: Invitations
  - name: kubernetes-clusters
    x-group: Kubernetes clusters
  - name: marketplace
    x-group: Marketplace
  - name: network
    x-group: Network
  - name: network-requests
    x-group: Network requests
  - name: notifications
    x-group: Notifications
  - name: oauth
    x-group: OAuth
  - name: oauth-clients
    x-group: OAuth clients
  - name: opencost
    x-group: OpenCost
  - name: organization
    x-group: Audit log
  - name: organizations
    x-group: Organizations
  - name: placement-alternatives
    x-group: Placement alternatives
  - name: reports
    x-group: Reports
  - name: sandboxes
    x-group: Sandboxes
  - name: settings
    x-group: Settings
  - name: sso
    x-group: Single sign-on
  - name: tenants
    x-group: Tenants
  - name: ticketing
    x-group: Ticketing
  - name: user
    x-group: Users
  - name: virtual-machines
    x-group: Virtual machines
  - name: virtual-tags
    x-group: Virtual tags
  - name: workflows
    x-group: Workflows
paths:
  /api/v1/tenant/sandboxes/{provider}/{sandbox_id}/exec:
    post:
      tags:
        - sandboxes
      summary: Run a command in a sandbox
      description: >-
        Runs a shell command in a running sandbox started through this API or
        the CostGraph MCP tools and returns its exit code and output. stdout and
        stderr hold at most 256 KiB each, and truncated is true when either was
        cut. timeout_ms limits the command, up to 55000; background true starts
        the command and returns at once. A sandbox the provider has ended is
        recorded as stopped and answers 404.
      parameters:
        - description: Tenant ID
          name: X-CostGraph-Tenant-ID
          in: header
          schema:
            type: string
        - description: Provider
          name: provider
          in: path
          required: true
          schema:
            type: string
        - description: Sandbox ID
          name: sandbox_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sandboxapi.ExecRequest'
        description: Command
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/responses.SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/sandboxapi.ExecResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    sandboxapi.ExecRequest:
      type: object
      required:
        - command
      properties:
        background:
          type: boolean
        command:
          type: string
          maxLength: 65536
        cwd:
          type: string
          maxLength: 4096
        env:
          type: object
          additionalProperties:
            type: string
        timeout_ms:
          type: integer
          maximum: 55000
          minimum: 1
    responses.SuccessResponse:
      type: object
      required:
        - message
        - status
      properties:
        data: {}
        message:
          type: string
          example: some message
        status:
          type: string
          example: success
    sandboxapi.ExecResult:
      type: object
      required:
        - exit_code
        - stderr
        - stdout
        - truncated
      properties:
        exit_code:
          type: integer
        stderr:
          type: string
        stdout:
          type: string
        truncated:
          type: boolean
    responses.ErrorResponse:
      type: object
      required:
        - message
        - status
      properties:
        message:
          type: string
          example: some message
        status:
          type: string
          example: error
  securitySchemes:
    ApiKeyAuth:
      description: API key for machine-to-machine authentication
      type: apiKey
      name: X-API-Key
      in: header

````

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