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

# Run code on the box

> Executes code inside the specified box. Supports multiple languages (bash, Python, TypeScript) and allows you to configure environment variables, arguments, working directory, and timeouts.



## OpenAPI

````yaml post /boxes/{boxId}/run-code
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}/run-code:
    post:
      tags:
        - Run Code
      summary: Run code on the box
      description: >-
        Executes code inside the specified box. Supports multiple languages
        (bash, Python, TypeScript) and allows you to configure environment
        variables, arguments, working directory, and timeouts.
      operationId: RunCodeController_runCode
      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/RunCode'
            examples:
              Basic:
                summary: Basic run code
                value:
                  code: print("Hello, World!")
              SpecialLanguage:
                summary: Special language
                value:
                  code: console.log("Hello, World!")
                  language: typescript
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunCodeResult'
      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" });

              // Run Python code
              const pythonResult = await box.runCode({
                code: `print("Hello from Python!")`,
                language: "python"
              });

              console.log("Python execution result:");
              console.log(`Exit code: ${pythonResult.exitCode}`);
              console.log(`Output:\n${pythonResult.stdout}`);
              if (pythonResult.stderr) {
                console.log(`Errors:\n${pythonResult.stderr}`);
              }
            }

            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")

                # Run Python code
                python_result = box.run_code(
                    code="print('Hello from Python!')",
                    language="python"
                )

                print("Python execution result:")
                print(f"Exit code: {python_result.exitCode}")
                print(f"Output:\n{python_result.stdout}")
                if python_result.stderr:
                    print(f"Errors:\n{python_result.stderr}")


            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// Run Python code\n\tpythonResult, err := box.RunCode(context.Background(), &gbox.RunCodeRequest{\n\t\tCode:     `print(\"Hello from Python!\")`,\n\t\tLanguage: \"python\",\n\t})\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to run Python code: %v\", err)\n\t}\n\n\tfmt.Println(\"Python execution result:\")\n\tfmt.Printf(\"Exit code: %d\\n\", pythonResult.ExitCode)\n\tfmt.Printf(\"Output:\\n%s\\n\", pythonResult.Stdout)\n\tif pythonResult.Stderr != \"\" {\n\t\tfmt.Printf(\"Errors:\\n%s\\n\", pythonResult.Stderr)\n\t}\n}"
components:
  schemas:
    RunCode:
      type: object
      properties:
        code:
          type: string
          description: The code to run
          example: |-
            print('Hello, World!')
            print(2 + 3)
        language:
          type: string
          enum:
            - bash
            - python
            - typescript
          default: python
          description: The language of the code.
          example: python
        envs:
          type: object
          description: The environment variables to run the code
          example:
            PYTHONPATH: /usr/lib/python
            DEBUG: 'true'
        argv:
          description: >-
            The arguments to run the code. For example, if you want to run
            "python index.py --help", you should pass ["--help"] as arguments.
          example:
            - '--help'
          type: array
          items:
            type: string
        workingDir:
          type: string
          description: >-
            The working directory of the code. It not provided, the code will be
            run in the `box.config.workingDir` directory.
          example: /home/user/scripts
        timeout:
          type: string
          description: >-
            The timeout of the code execution. If the code execution times out,
            the exit code will be 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: CodeExecutionTimeout
      title: Run Code
      description: Request parameters for running code in various languages
      required:
        - code
    RunCodeResult:
      type: object
      properties:
        exitCode:
          type: number
          description: The exit code of the code
          example: 0
        stdout:
          type: string
          description: The stdout of the code
          example: |-
            Hello, World!
            5
        stderr:
          type: string
          description: The stderr of the code
          example: ''
      title: Run Code Result
      description: Result of code 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

````