List sandboxes - Documentation

You can use the Sandbox.list() method to list sandboxes.

Once you have information about a running sandbox, you can connect to it using the Sandbox.connect() method.

import { Sandbox } from 'novita-sandbox/code-interpreter'

// Create a sandbox.
const sandbox = await Sandbox.create({
  metadata: {
    name: 'My Sandbox',
  },
})

// List all running sandboxes.
const runningSandboxesPaginator = await Sandbox.list({
  query: {
    state: ["running"],
  },
})

const runningSandboxes = await runningSandboxesPaginator.nextItems()
const runningSandbox = runningSandboxes[0]

console.log('Running sandbox metadata:', runningSandbox.metadata)
console.log('Running sandbox id:', runningSandbox.sandboxId)
console.log('Running sandbox started at:', runningSandbox.startedAt)
console.log('Running sandbox ends at:', runningSandbox.endAt)
console.log('Running sandbox template id:', runningSandbox.templateId)
console.log('Running sandbox state:', runningSandbox.state)

await sandbox.kill()

from novita_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

sandbox = Sandbox.create(
  metadata= {
    'name': 'My Sandbox',
  },
)

# List all running sandboxes.
running_sandboxes_paginator = Sandbox.list(
  query=SandboxQuery(
    state=[SandboxState.RUNNING],
  ),
)

running_sandboxes = running_sandboxes_paginator.next_items()

running_sandbox = running_sandboxes[0]
print('Running sandbox metadata:', running_sandbox.metadata)
print('Running sandbox id:', running_sandbox.sandbox_id)
print('Running sandbox started at:', running_sandbox.started_at)
print('Running sandbox end at:', running_sandbox.end_at)
print('Running sandbox template id:', running_sandbox.template_id)
print('Running sandbox state:', running_sandbox.state)

sandbox.kill()

Filtering sandboxes

You can filter sandboxes by specifying Metadata key-value pairs. Specifying multiple key-value pairs returns sandboxes that match all of them. This can be useful when you have a large number of sandboxes and want to find only specific ones. The filtering is performed on the server.

import { Sandbox } from 'novita-sandbox/code-interpreter'

// Create a sandbox with metadata.
const sandbox = await Sandbox.create({
  metadata: {
    env: 'dev',
    app: 'my-app',
    userId: '123',
  },
})

// List all running sandboxes that have the `userId` key with value `123` and the `env` key with value `dev`.
const runningSandboxesPaginator = await Sandbox.list({
  query: {
    metadata: { userId: '123', env: 'dev' },
  },
})

const runningSandboxes = await runningSandboxesPaginator.nextItems()
for (const runningSandbox of runningSandboxes) {
  console.log(`list running sandbox (${runningSandbox.sandboxId}) metadata:`, runningSandbox.metadata)
}

await sandbox.kill()

from novita_sandbox.code_interpreter import Sandbox, SandboxQuery

# Create sandbox with metadata.
sandbox = Sandbox.create(
    metadata={
        "env": "dev",
        "app": "my-app",
        "user_id": "123",
    },
)

# List all running sandboxes that have the `user_id` key with value `123` and the `env` key with value `dev`.
paginator = Sandbox.list(
    query=SandboxQuery(
        metadata={
            "user_id": "123",
            "env": "dev",
        }
    ),
)

sandbox.kill()

Listing sandboxes

Pagination is now supported by the Sandbox.list() method. To learn more about pagination techniques with the updated method, refer to the advanced pagination section.

import { Sandbox } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

const paginator = Sandbox.list()

// Get the first page of sandboxes (running and paused)
const firstPage = await paginator.nextItems()
if (paginator.hasNext) {
    // Get the next page of sandboxes
    const nextPage = await paginator.nextItems()
}

await sandbox.kill()

from novita_sandbox.code_interpreter import Sandbox

sandbox = Sandbox.create()

# List all sandboxes (running and paused)
paginator = Sandbox.list()

firstPage = paginator.next_items()
if paginator.has_next:
    nextPage = paginator.next_items()

sandbox.kill()

Filtering sandboxes

You can filter sandboxes based on their current status. The state parameter accepts “running”, “paused”, or both to return sandboxes in the specified states.

import { Sandbox } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

// List all sandboxes that are running or paused.
const paginator = Sandbox.list({
  query: {
    state: ['running', 'paused'],
  },
})

const sandboxes = await paginator.nextItems()

await sandbox.kill()

from novita_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

sandbox = Sandbox.create()

# List all sandboxes that are running or paused.
paginator = Sandbox.list(
    query=SandboxQuery(
        state=[SandboxState.RUNNING, SandboxState.PAUSED],
    ),
)

# Get the first page of sandboxes (running and paused)
sandboxes = paginator.next_items()

sandbox.kill()

You can specify metadata key-value pairs during sandbox creation and later use them when listing sandboxes.

import { Sandbox } from 'novita-sandbox/code-interpreter'

// Create sandbox with metadata.
const sandbox = await Sandbox.create({
  metadata: {
    env: 'dev',
    app: 'my-app',
    userId: '123',
  },
})

// List all sandboxes that have the `userId` key with value `123` and the `env` key with value `dev`.
const paginator = Sandbox.list({
  query: {
    metadata: { userId: '123', env: 'dev' },
  },
})

const sandboxes = await paginator.nextItems()

await sandbox.kill()

from novita_sandbox.code_interpreter import Sandbox, SandboxQuery

# Create sandbox with metadata.
sandbox = Sandbox.create(
    metadata={
        "env": "dev",
        "app": "my-app",
        "user_id": "123",
    },
)

# List all sandboxes that have the `user_id` key with value `123` and the `env` key with value `dev`.
paginator = Sandbox.list(
    query=SandboxQuery(
        metadata={
            "user_id": "123",
            "env": "dev",
        }
    ),
)

sandboxes = paginator.next_items()

sandbox.kill()

Advanced pagination

For finer control over pagination, specify the number of items to return per page (the default and maximum is 100) and provide an offset parameter (nextToken or next_token) to indicate where pagination should begin.

import { Sandbox } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

const paginator = Sandbox.list({
  limit: 100,
  // nextToken: '<base64-encoded-token>',
})

// Fetch the next page
await paginator.nextItems()

// Additional paginator properties
// Whether there is a next page
console.log("paginator.hasNext: ", paginator.hasNext)

// Next page token
console.log("paginator.nextToken: ", paginator.nextToken)

await sandbox.kill()

from novita_sandbox.code_interpreter import Sandbox

sandbox = Sandbox.create()

paginator = Sandbox.list(
    limit=100,
    # next_token='<base64-encoded-token>',
)

# Fetch the next page
paginator.next_items()

# Whether there is a next page
print("paginator.has_next: ", paginator.has_next)

# Next page offset parameter
print("paginator.next_token: ", paginator.next_token)

sandbox.kill()

You can retrieve all pages by iterating through the paginator. hasNext / has_next is initially true before the first page is fetched and becomes false after the last page is returned.

import { Sandbox, SandboxInfo } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

const paginator = Sandbox.list()

const sandboxes: SandboxInfo[] = []
while (paginator.hasNext) {
  const items = await paginator.nextItems()
  sandboxes.push(...items)
}

for (const sandbox of sandboxes) {
  console.log(`list sandbox (${sandbox.sandboxId})`)
}

await sandbox.kill()

from novita_sandbox.code_interpreter import Sandbox, SandboxInfo

sandbox = Sandbox.create()

paginator = Sandbox.list()

# Get all sandboxes
sandboxes: list[SandboxInfo] = []
while paginator.has_next:
    items = paginator.next_items()
    sandboxes.extend(items)

sandbox.kill()

​Filtering sandboxes

​Listing sandboxes

​Filtering sandboxes

​Advanced pagination

Filtering sandboxes

Listing sandboxes

Filtering sandboxes

Advanced pagination