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

# Create android box

> Provisions a new Android box that you can operate through the GBOX SDK. Use this endpoint when you want to create a fresh Android environment for testing, automation, or agent execution.



## OpenAPI

````yaml post /boxes/android
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/android:
    post:
      tags:
        - Box
      summary: Create android box
      description: >-
        Provisions a new Android box that you can operate through the GBOX SDK.
        Use this endpoint when you want to create a fresh Android environment
        for testing, automation, or agent execution.
      operationId: BoxController_createAndroid
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAndroidBox'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AndroidBox'
      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: "android" });

              console.log(`Android box created: ${box.data.id}`);
            }

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

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

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

            print(f"Android box created: {box.data.id}")
        - lang: Go
          source: "package main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n)\n\nfunc main() {\n\tgboxSDK := gbox.NewGboxSDK(os.Getenv(\"GBOX_API_KEY\"))\n\n\tbox, err := gboxSDK.Create(context.Background(), gbox.CreateBoxRequest{\n\t\tType: \"android\",\n\t})\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to create box: %v\", err)\n\t}\n\n\tfmt.Printf(\"Android box created: %s\\n\", box.Data.ID)\n}"
components:
  schemas:
    CreateAndroidBox:
      type: object
      properties:
        wait:
          type: boolean
          default: true
          description: Wait for the box operation to be completed, default is true
          title: BoxWait
          example: true
        timeout:
          type: string
          description: >-
            Timeout for waiting the box to transition from pending to running
            state, default is 30s. If the box doesn't reach running state within
            this timeout, the API will return HTTP status code 408. The
            timed-out box will be automatically deleted and will not count
            towards your quota.


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

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

            Default: 30s

            Maximum allowed: 5m
          example: 30s
          default: 30s
          title: BoxWaitConfig
        config:
          description: Configuration for an Android box instance
          title: CreateAndroidBox
          example:
            labels:
              app: mobile-testing
              version: v1.0
            envs:
              ANDROID_LOG_TAGS: '*:V'
              ADB_TRACE: all
            expiresIn: 15m
          allOf:
            - $ref: '#/components/schemas/CreateAndroidBoxConfig'
      title: Create Android Box
      description: Request body for creating a new Android box instance
    AndroidBox:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the box
          title: BaseBox
          example: c9bdc193-b54b-4ddb-a035-5ac0c598d32d
        status:
          type: string
          enum:
            - pending
            - running
            - error
            - terminated
          description: The current status of a box instance
          title: BaseBox
          example: running
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp of the box
          title: BaseBox
          example: '2024-01-15T10:30:00.000Z'
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp of the box
          title: BaseBox
          example: '2024-01-15T10:35:00.000Z'
        expiresAt:
          type: string
          format: date-time
          description: Expiration timestamp of the box
          title: BaseBox
          example: '2024-01-15T10:40:00.000Z'
          nullable: true
        reason:
          type: string
          description: The reason for the current status, if any
          title: BaseBox
          example: Box terminated by user
          nullable: true
        type:
          type: string
          enum:
            - android
          default: android
          description: Box type is Android
          title: AndroidBox
          example: android
        config:
          description: Configuration for an Android box instance
          title: AndroidBox
          example:
            os:
              version: '12'
            deviceType: virtual
            workingDir: /data/local/tmp
            labels:
              app: mobile-testing
              env: staging
            envs:
              ANDROID_HOME: /opt/android-sdk
              DISPLAY: ':1'
            cpu: 2
            memory: 2048
            storage: 20
          allOf:
            - $ref: '#/components/schemas/AndroidConfig'
      title: Android Box
      description: Android box instance with full configuration and status
      required:
        - id
        - status
        - createdAt
        - updatedAt
        - expiresAt
        - type
        - config
    CreateAndroidBoxConfig:
      type: object
      properties:
        labels:
          type: object
          additionalProperties:
            type: string
          description: >-
            Key-value pairs of labels for the box. Labels are used to add custom
            metadata to help identify, categorize, and manage boxes. Common use
            cases include project names, environments, teams, applications, or
            any other organizational tags that help you organize and filter your
            boxes.
          title: CreateBoxConfig
          example:
            project: web-automation
            environment: testing
            owner: john-doe
            purpose: e2e-testing
        envs:
          type: object
          additionalProperties:
            type: string
          description: >-
            Environment variables for the box. These variables will be available
            in all operations including command execution, code running, and
            other box behaviors
          title: CreateBoxConfig
          example:
            DEBUG: 'true'
            API_URL: https://api.example.com
        keepAlive:
          type: string
          description: >-
            Keep alive duration on activity. When set to a positive value (e.g.,
            '5m'), the box expiration time (expiresIn) will be automatically
            extended to ensure at least this duration remains whenever there is
            an box operation on this specific box. For example, when calling UI
            Action, FS, Browser, Command, Media, or Run Code operations with
            this box's boxId, the box will be kept alive. If keepAlive is '5m'
            and the box has 2 minutes remaining, any operation on this boxId
            will extend the remaining time to 5 minutes. Set to '0ms' to disable
            automatic keep alive extension. This helps keep frequently-used
            boxes alive without manual intervention.


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

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

            Default: 0ms
          example: 0ms
          default: 0ms
          title: CreateBoxConfig
        deviceType:
          type: string
          enum:
            - virtual
            - physical
          description: Device type - virtual or physical Android device
          title: AndroidConfig
          example: virtual
          default: virtual
        expiresIn:
          type: string
          description: >-
            The box will be alive for the given duration


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

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

            Default: 60m
          example: 60m
          default: 60m
          title: CreateBoxConfig
      title: Create Android Box Config
      description: Configuration for a Android box instance
    AndroidConfig:
      type: object
      properties:
        os:
          description: Android operating system configuration
          title: AndroidConfig
          example:
            version: '12'
          allOf:
            - $ref: '#/components/schemas/AndroidOsConfig'
        deviceType:
          type: string
          enum:
            - virtual
            - physical
          description: Device type - virtual or physical Android device
          title: AndroidConfig
          example: virtual
          default: virtual
        workingDir:
          type: string
          description: >-
            Working directory path for the box. This directory serves as the
            default starting point for all operations including command
            execution, code running, and file system operations. When you
            execute commands or run code, they will start from this directory
            unless explicitly specified otherwise.
          title: AndroidConfig
          example: /data/local/tmp
        labels:
          type: object
          additionalProperties:
            type: string
          description: >-
            Key-value pairs of labels for the box. Labels are used to add custom
            metadata to help identify, categorize, and manage boxes. Common use
            cases include project names, environments, teams, applications, or
            any other organizational tags that help you organize and filter your
            boxes.
          title: AndroidConfig
          example:
            app: mobile-testing
            environment: staging
            team: qa
            device: pixel-6
        envs:
          type: object
          additionalProperties:
            type: string
          description: >-
            Environment variables for the box. These variables will be available
            in all operations including command execution, code running, and
            other box behaviors
          title: AndroidConfig
          example:
            ANDROID_HOME: /opt/android-sdk
            DISPLAY: ':1'
        cpu:
          type: number
          description: CPU cores allocated to the box
          title: AndroidConfig
          example: 2
        memory:
          type: number
          description: Memory allocated to the box in MiB
          title: AndroidConfig
          example: 2048
        storage:
          type: number
          description: Storage allocated to the box in GiB
          title: AndroidConfig
          example: 20
      title: Android Config
      description: Complete configuration for Android box instance
      required:
        - os
        - labels
        - envs
        - cpu
        - memory
        - storage
    AndroidOsConfig:
      type: object
      properties:
        version:
          type: string
          enum:
            - '12'
            - '13'
            - '15'
          description: Supported Android versions
          title: AndroidOsConfig
          example: '12'
      title: Android OS Config
      description: Android operating system configuration
      required:
        - version
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: >-
        Enter your API Key in the format: Bearer <token>. Get it from
        https://gbox.ai

````