---
title: "Create linux box"
method: POST
path: "/boxes/linux"
tags: ["Box"]
---

# Create linux box

`POST /boxes/linux`

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.

## Request body

- CreateLinuxBox — Request body for creating a new Linux box instance
  - `wait` boolean — Wait for the box operation to be completed, default is true
  - `timeout` string — 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
  - `config` CreateLinuxBoxConfig — Configuration for a Linux box instance
    - `labels` object — 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.
    - `envs` object — Environment variables for the box. These variables will be available in all operations including command execution, code running, and other box behaviors
    - `keepAlive` string — 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
    - `deviceType` 'container' | 'vm' — Device type - container or vm Linux device
    - `snapshotName` string — Snapshot name - snapshot for creating vm linux box
    - `expiresIn` string — 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

## Response `201`

- LinuxBox — Linux box instance with full configuration and status
  - `id` string, required — Unique identifier for the box
  - `status` 'pending' | 'running' | 'error' | 'terminated', required — The current status of a box instance
  - `createdAt` string, date-time, required — Creation timestamp of the box
  - `updatedAt` string, date-time, required — Last update timestamp of the box
  - `expiresAt` string, date-time, nullable, required — Expiration timestamp of the box
  - `reason` string, nullable — The reason for the current status, if any
  - `type` 'linux', required — Box type is Linux
  - `config` LinuxConfig, required — Complete configuration for Linux box instance
    - `os` LinuxOsConfig, required — Linux operating system configuration
      - `version` string, required — OS version string (e.g. 'ubuntu-20.04')
    - `workingDir` string, required — 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.
    - `labels` object, required — 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.
    - `envs` object, required — Environment variables for the box. These variables will be available in all operations including command execution, code running, and other box behaviors
    - `cpu` number, required — CPU cores allocated to the box
    - `memory` number, required — Memory allocated to the box in MiB
    - `storage` number, required — Storage allocated to the box in GiB.
    - `publicIp` string, required — Public IP allocated to the box.
    - `deviceType` 'container' | 'vm' — Device type - container or vm Linux device
    - `snapshotName` string — Snapshot name
    - `snapshotId` string — Snapshot id

---

[API](https://skmtc.net/babelcloud/apis/gbox-open-api.md) · [All operations](https://skmtc.net/babelcloud/apis/gbox-open-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/babelcloud/gbox-open-api/versions/d655577fa915/schema)