Sign in

v48

latestOpenAPI 3.0.0raw.githubusercontent.com2025-12-0297180624.8 KB
Box

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.

post/boxes/linux

Request body

waitboolean

Wait for the box operation to be completed, default is true

timeoutstring

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 request

{
  "wait": true,
  "timeout": "30s",
  "config": {
    "labels": {
      "project": "web-automation",
      "environment": "testing",
      "owner": "john-doe",
      "purpose": "e2e-testing"
    },
    "envs": {
      "DEBUG": "true",
      "API_URL": "https://api.example.com"
    },
    "keepAlive": "0ms",
    "deviceType": "container",
    "expiresIn": "60m"
  }
}

Response

idstring required

Unique identifier for the box

status'pending' | 'running' | 'error' | 'terminated' required

The current status of a box instance

createdAtstring date-time required

Creation timestamp of the box

updatedAtstring date-time required

Last update timestamp of the box

expiresAtstring date-time nullable required

Expiration timestamp of the box

reasonstring nullable

The reason for the current status, if any

type'linux' required

Box type is Linux

Example response

{
  "id": "c9bdc193-b54b-4ddb-a035-5ac0c598d32d",
  "status": "running",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z",
  "expiresAt": "2024-01-15T10:40:00.000Z",
  "reason": "Box terminated by user",
  "type": "linux",
  "config": {
    "os": {
      "version": "ubuntu-20.04"
    },
    "workingDir": "/home/user",
    "labels": {
      "project": "web-scraper",
      "environment": "production",
      "team": "backend",
      "version": "v1.2.0"
    },
    "envs": {
      "MY_ENV_KEY": "env value"
    },
    "cpu": 2,
    "memory": 1024,
    "storage": 30,
    "publicIp": "8.8.8.8",
    "deviceType": "container"
  }
}