Skip to main content
You can use the Sandbox.list() method to list sandboxes.
Once you have information about 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 end at:', runningSandbox.endAt)
console.log('Running sandbox template id:', runningSandbox.templateId)
console.log('Running sandbox state:', runningSandbox.state)

await sandbox.kill()

​
Filtering sandboxes

You can filter sandboxes by specifying Metadata key value pairs. Specifying multiple key value pairs will return 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 has `userId` key with value `123` and `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()

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

​
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()
You can specify the metadata key value pairs to filter sandboxes during Sandbox creation. 
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 has `userId` key with value `123` and `env` key with value `dev`.
const paginator = Sandbox.list({
  query: {
    metadata: { userId: '123', env: 'dev' },
  },
})

const sandboxes = await paginator.nextItems()

await 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()
You can retrieve all pages by iterating through the paginator to check for the next page using hasNext or has_next, and continue fetching until no pages remain. 
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()
Last modified on June 4, 2026