> ## 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 linux box > Provisions a new Linux box that you can operate through the GBOX SDK. Use this endpoint when you want to create a fresh Linux environment for testing, automation, or agent execution. ## OpenAPI ````yaml post /boxes/linux 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/linux: post: tags: - Box summary: Create linux box description: >- Provisions a new Linux box that you can operate through the GBOX SDK. Use this endpoint when you want to create a fresh Linux environment for testing, automation, or agent execution. operationId: BoxController_createLinux parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateLinuxBox' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/LinuxBox' 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" }); console.log(`Linux 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="linux") print(f"Linux 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: \"linux\",\n\t})\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to create box: %v\", err)\n\t}\n\n\tfmt.Printf(\"Linux box created: %s\\n\", box.Data.ID)\n}" components: schemas: CreateLinuxBox: 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 a Linux box instance title: CreateLinuxBox example: labels: project: web-automation environment: testing envs: DEBUG: 'true' API_URL: https://api.example.com expiresIn: 60m allOf: - $ref: '#/components/schemas/CreateLinuxBoxConfig' title: Create Linux Box description: Request body for creating a new Linux box instance LinuxBox: 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: - linux default: linux description: Box type is Linux title: LinuxBox example: linux config: description: Configuration for a Linux box instance title: LinuxBox example: os: version: ubuntu-20.04 deviceType: physical workingDir: /home/user labels: environment: development team: qa envs: NODE_ENV: production PATH: /usr/bin:/bin cpu: 2 memory: 1024 storage: 30 allOf: - $ref: '#/components/schemas/LinuxConfig' title: Linux Box description: Linux box instance with full configuration and status required: - id - status - createdAt - updatedAt - expiresAt - type - config CreateLinuxBoxConfig: 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: - container - vm description: Device type - container or vm Linux device title: LinuxConfig example: container default: container snapshotName: type: string title: LinuxConfig description: Snapshot name - snapshot for creating vm linux box 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 Linux Box Config description: Configuration for a Linux box instance LinuxConfig: type: object properties: os: description: Operating system configuration title: LinuxConfig example: version: ubuntu-20.04 allOf: - $ref: '#/components/schemas/LinuxOsConfig' 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: LinuxConfig example: /home/user 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: LinuxConfig example: project: web-scraper environment: production team: backend version: v1.2.0 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: LinuxConfig example: MY_ENV_KEY: env value cpu: type: number description: CPU cores allocated to the box title: LinuxConfig example: 2 memory: type: number description: Memory allocated to the box in MiB title: LinuxConfig example: 1024 storage: type: number description: Storage allocated to the box in GiB. title: LinuxConfig example: 30 publicIp: type: string description: Public IP allocated to the box. title: LinuxConfig example: 8.8.8.8 deviceType: type: string enum: - container - vm description: Device type - container or vm Linux device title: LinuxConfig example: container default: container snapshotName: type: string description: Snapshot name title: LinuxConfig snapshotId: type: string description: Snapshot id title: LinuxConfig title: Linux Config description: Complete configuration for Linux box instance required: - os - workingDir - labels - envs - cpu - memory - storage - publicIp LinuxOsConfig: type: object properties: version: type: string description: OS version string (e.g. 'ubuntu-20.04') title: LinuxOsConfig example: ubuntu-20.04 title: Linux OS Config description: Linux operating system configuration required: - version securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http description: >- Enter your API Key in the format: Bearer . Get it from https://gbox.ai ````