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

# Exec command

> Execute a command on a running box. This endpoint allows you to send commands to the box and receive the output



## OpenAPI

````yaml post /boxes/{boxId}/commands
openapi: 3.0.0
info:
  title: GBOX Open API
  description: GBOX Open API Documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://gbox.ai/api/v1
    description: Production Server
security: []
tags: []
paths:
  /boxes/{boxId}/commands:
    post:
      tags:
        - Command
      summary: Exec command
      description: >-
        Execute a command on a running box. This endpoint allows you to send
        commands to the box and receive the output
      operationId: CommandController_execCommand
      parameters:
        - name: boxId
          required: true
          in: path
          description: Box ID
          schema:
            example: c9bdc193-b54b-4ddb-a035-5ac0c598d32d
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Command'
            examples:
              Basic:
                summary: Basic command use
                value:
                  command: ls -l
              SetTimeout:
                summary: Set timeout
                value:
                  command: sleep 10
                  timeout: 5s
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResult'
      security:
        - bearer: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import GboxSDK from "gbox-sdk";

            const gboxSDK = new GboxSDK({
              apiKey: process.env["GBOX_API_KEY"] // This is the default and can be omitted
            });

            async function main() {
              const box = await gboxSDK.create({ type: "linux" });

              // Execute a simple command
              const result = await box.command({
                command: "ls -l"
              });

              console.log(`Command output: ${result.stdout}`);
              console.log(`Command error: ${result.stderr}`);
              console.log(`Exit code: ${result.exitCode}`);

              // Execute command with timeout
              const resultWithTimeout = await box.command({
                command: "sleep 10",
                timeout: "5s"
              });

              console.log(`Timeout result: ${JSON.stringify(resultWithTimeout, null, 2)}`);
            }

            main();
        - lang: Python
          source: |-
            import os
            from gbox_sdk import GboxSDK

            def main():
                gbox_sdk = GboxSDK(api_key=os.environ["GBOX_API_KEY"])

                box = gbox_sdk.create(type="linux")

                # Execute a simple command
                result = box.command(
                    command="ls -l"
                )

                print(f"Command output: {result.stdout}")
                print(f"Command error: {result.stderr}")
                print(f"Exit code: {result.exitCode}")

                # Execute command with timeout
                result_with_timeout = box.command(
                    command="sleep 10",
                    timeout="5s"
                )

                print(f"Timeout result: {result_with_timeout}")

            if __name__ == "__main__":
                main()
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\t\"github.com/gbox/gbox-sdk-go\"\n)\n\nfunc main() {\n\tgboxSDK := gbox.NewGboxSDK(os.Getenv(\"GBOX_API_KEY\"))\n\n\tbox, err := gboxSDK.Create(context.Background(), gbox.CreateOptions{Type: \"linux\"})\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to create linux box: %v\", err)\n\t}\n\n\t// Execute a simple command\n\tresult, err := box.Command(context.Background(), &gbox.CommandRequest{\n\t\tCommand: \"ls -l\",\n\t})\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to execute command: %v\", err)\n\t}\n\n\tfmt.Printf(\"Command output: %s\\n\", result.Stdout)\n\tfmt.Printf(\"Command error: %s\\n\", result.Stderr)\n\tfmt.Printf(\"Exit code: %d\\n\", result.ExitCode)\n\n\t// Execute command with timeout\n\tresultWithTimeout, err := box.Command(context.Background(), &gbox.CommandRequest{\n\t\tCommand: \"sleep 10\",\n\t\tTimeout: \"5s\",\n\t})\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to execute command with timeout: %v\", err)\n\t}\n\n\tfmt.Printf(\"Timeout result: %v\\n\", resultWithTimeout)\n}"
components:
  schemas:
    Command:
      type: object
      properties:
        command:
          type: string
          description: The command to run
          example: ls -la
        envs:
          type: object
          description: The environment variables to run the command
          example:
            PATH: /usr/bin:/bin
            NODE_ENV: production
        workingDir:
          type: string
          description: >-
            The working directory of the command. It not provided, the command
            will be run in the `box.config.workingDir` directory.
          example: /home/user/projects
        timeout:
          type: string
          description: >-
            The timeout of the command. If the command times out, the exit code
            will be 124. For example: 'timeout 5s sleep 10s' will result in exit
            code 124.


            Supported time units: ms (milliseconds), s (seconds), m (minutes), h
            (hours)

            Example formats: "500ms", "30s", "5m", "1h"

            Default: 30s
          example: 30s
          default: 30s
          title: CommandTimeout
      title: Command
      description: Command execution request parameters
      required:
        - command
    CommandResult:
      type: object
      properties:
        exitCode:
          type: number
          description: The exit code of the command
          example: 0
        stdout:
          type: string
          description: The standard output of the command
          example: |-
            total 16
            drwxr-xr-x  4 user user 4096 Jan 15 10:30 .
            drwxr-xr-x  3 user user 4096 Jan 15 10:25 ..
        stderr:
          type: string
          description: The standard error output of the command
          example: ''
      title: Command Result
      description: Result of command execution
      required:
        - exitCode
        - stdout
        - stderr
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: >-
        Enter your API Key in the format: Bearer <token>. Get it from
        https://gbox.ai

````