Create linux box

JavaScript

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();

{
  "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",
  "type": "linux",
  "config": {
    "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
  },
  "reason": "Box terminated by user"
}

POST

boxes

linux

JavaScript

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();

{
  "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",
  "type": "linux",
  "config": {
    "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
  },
  "reason": "Box terminated by user"
}

Authorizations

Authorization

string

header

required

Enter your API Key in the format: Bearer . Get it from https://gbox.ai

Body

application/json

Request body for creating a new Linux box instance

wait

boolean

default:true

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

Example:

true

timeout

string

default:30s

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"

config

CreateLinuxBox · object

Configuration for a Linux box instance

Show child attributes

config.labels

CreateBoxConfig · 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.

Show child attributes

config.labels.{key}

string

Example:

{
  "project": "web-automation",
  "environment": "testing",
  "owner": "john-doe",
  "purpose": "e2e-testing"
}

config.envs

CreateBoxConfig · object

Environment variables for the box. These variables will be available in all operations including command execution, code running, and other box behaviors

Show child attributes

config.envs.{key}

string

Example:

{
  "DEBUG": "true",
  "API_URL": "https://api.example.com"
}

config.keepAlive

string

default:0ms

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"

config.deviceType

enum<string>

default:container

Device type - container or vm Linux device

Available options:

container,

vm

Example:

"container"

config.snapshotName

string

Snapshot name - snapshot for creating vm linux box

config.expiresIn

string

default:60m

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"

Example:

{
  "labels": {
    "project": "web-automation",
    "environment": "testing"
  },
  "envs": {
    "DEBUG": "true",
    "API_URL": "https://api.example.com"
  },
  "expiresIn": "60m"
}

Response

201 - application/json

Linux box instance with full configuration and status

string

required

Unique identifier for the box

Example:

"c9bdc193-b54b-4ddb-a035-5ac0c598d32d"

status

enum<string>

required

The current status of a box instance

Available options:

pending,

running,

error,

terminated

Example:

"running"

createdAt

string<date-time>

required

Creation timestamp of the box

Example:

"2024-01-15T10:30:00.000Z"

updatedAt

string<date-time>

required

Last update timestamp of the box

Example:

"2024-01-15T10:35:00.000Z"

expiresAt

string<date-time> | null

required

Expiration timestamp of the box

Example:

"2024-01-15T10:40:00.000Z"

type

enum<string>

default:linux

required

Box type is Linux

Available options:

linux

Example:

"linux"

config

LinuxBox · object

required

Configuration for a Linux box instance

Show child attributes

config.os

LinuxConfig · object

required

Operating system configuration

Show child attributes

config.os.version

string

required

OS version string (e.g. 'ubuntu-20.04')

Example:

"ubuntu-20.04"

Example:

{ "version": "ubuntu-20.04" }

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

Example:

"/home/user"

config.labels

LinuxConfig · object

required

Show child attributes

config.labels.{key}

string

Example:

{
  "project": "web-scraper",
  "environment": "production",
  "team": "backend",
  "version": "v1.2.0"
}

config.envs

LinuxConfig · object

required

Environment variables for the box. These variables will be available in all operations including command execution, code running, and other box behaviors

Show child attributes

config.envs.{key}

string

Example:

{ "MY_ENV_KEY": "env value" }

config.cpu

number

required

CPU cores allocated to the box

Example:

2

config.memory

number

required

Memory allocated to the box in MiB

Example:

1024

config.storage

number

required

Storage allocated to the box in GiB.

Example:

30

config.publicIp

string

required

Public IP allocated to the box.

Example:

"8.8.8.8"

config.deviceType

enum<string>

default:container

Device type - container or vm Linux device

Available options:

container,

vm

Example:

"container"

config.snapshotName

string

Snapshot name

config.snapshotId

string

Snapshot id

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
}

reason

string | null

The reason for the current status, if any

Example:

"Box terminated by user"

Create android box List box

⌘I

Model

Box

UI Action

Run Code

Command

File System

Browser

Android

Media

Authorizations

Body

Response