Add filtering sandboxes by state in the SDKs

.changeset/stupid-pens-judge.md

@@ -0,0 +1,7 @@
+---
+'@e2b/python-sdk': minor
+'e2b': minor
+'@e2b/cli': minor
+---
+
+Adds filtering sandboxes by state in the SDKs and display of the state in the CLI

apps/web/src/app/(docs)/docs/sandbox/connect/page.mdx

@@ -12,28 +12,28 @@ To connect to a running sandbox, you first need to retrieve its ID. You can do t
 import { Sandbox } from "@e2b/code-interpreter"
 
 // Get all running sandboxes
-const runningSandboxes = await Sandbox.list() // $HighlightLine
+const { sandboxes } = await Sandbox.list({ state: ['running'] }) // $HighlightLine
 
-if (runningSandboxes.length === 0) {
+if (sandboxes.length === 0) {
   throw new Error("No running sandboxes found")
 }
 
 // Get the ID of the sandbox you want to connect to
-const sandboxId = runningSandboxes[0].sandboxId
+const sandboxId = sandboxes[0].sandboxId
 ```
 
 ```python
 from e2b_code_interpreter import Sandbox
 
 # Get all running sandboxes
-running_sandboxes = Sandbox.list() # $HighlightLine
+running_sandboxes = Sandbox.list(state=['running']) # $HighlightLine
 
 # Get the ID of the sandbox you want to connect to
-if len(running_sandboxes) == 0:
+if len(running_sandboxes.sandboxes) == 0:
   raise Exception("No running sandboxes found")
 
 # Get the ID of the sandbox you want to connect to
-sandbox_id = running_sandboxes[0].sandbox_id
+sandbox_id = running_sandboxes.sandboxes[0].sandbox_id
 ```
 </CodeGroup>
 
@@ -46,14 +46,14 @@ Now that you have the sandbox ID, you can connect to the sandbox using the `Sand
 import { Sandbox } from "@e2b/code-interpreter"
 
 // Get all running sandboxes
-const runningSandboxes = await Sandbox.list()
+const { sandboxes } = await Sandbox.list({ state: ['running'] })
 
-if (runningSandboxes.length === 0) {
+if (sandboxes.length === 0) {
   throw new Error("No running sandboxes found")
 }
 
 // Get the ID of the sandbox you want to connect to
-const sandboxId = runningSandboxes[0].sandboxId
+const sandboxId = sandboxes[0].sandboxId
 
 // Connect to the sandbox
 const sandbox = await Sandbox.connect(sandboxId) // $HighlightLine
@@ -65,13 +65,13 @@ const sandbox = await Sandbox.connect(sandboxId) // $HighlightLine
 from e2b_code_interpreter import Sandbox
 
 # Get all running sandboxes
-running_sandboxes = Sandbox.list()
+running_sandboxes = Sandbox.list(state=['running'])
 
 # Get the ID of the sandbox you want to connect to
-if len(running_sandboxes) == 0:
+if len(running_sandboxes.sandboxes) == 0:
   raise Exception("No running sandboxes found")
 
-sandbox_id = running_sandboxes[0].sandbox_id
+sandbox_id = running_sandboxes.sandboxes[0].sandbox_id
 
 # Connect to the sandbox
 sandbox = Sandbox.connect(sandbox_id) # $HighlightLine

apps/web/src/app/(docs)/docs/sandbox/list/page.mdx

@@ -18,8 +18,8 @@ const sandbox = await Sandbox.create({
   },
 })
 
-const runningSandboxes = await Sandbox.list() // $HighlightLine
-const runningSandbox = runningSandboxes[0]
+const runningSandboxes = await Sandbox.list({ state: ['running'] }) // $HighlightLine
+const runningSandbox = runningSandboxes.sandboxes[0]
 console.log('Running sandbox metadata:', runningSandbox.metadata)
 console.log('Running sandbox id:', runningSandbox.sandboxId)
 console.log('Running sandbox started at:', runningSandbox.startedAt)
@@ -34,8 +34,8 @@ sandbox = Sandbox({
   },
 })
 
-running_sandboxes = sandbox.list() # $HighlightLine
-running_sandbox = running_sandboxes[0]
+running_sandboxes = sandbox.list(state=['running']) # $HighlightLine
+running_sandbox = running_sandboxes.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)
@@ -86,7 +86,8 @@ const sandbox = await Sandbox.create({
 })
 
 // List running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
-const runningSandboxes = await Sandbox.list({
+const { sandboxes } = await Sandbox.list({
+    state: ['running'],
     filters: { userId: '123', env: 'dev' } // $HighlightLine
 })
 ```
@@ -103,7 +104,9 @@ sandbox = Sandbox(
 )
 
 # List running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
-running_sandboxes = Sandbox.list(filters={
+running_sandboxes = Sandbox.list(
+  state=['running'],
+  filters={
     "userId": "123", "env": "dev" # $HighlightLine
 })
 ```

apps/web/src/app/(docs)/docs/sandbox/metadata/page.mdx

@@ -23,12 +23,12 @@ const sandbox = await Sandbox.create({
 })
 
 // List running sandboxes and access metadata.
-const runningSandboxes = await Sandbox.list()
+const { sandboxes } = await Sandbox.list({ state: ['running'] })
 // Will print:
 // {
 //   'userId': '123',
 // }
-console.log(runningSandboxes[0].metadata)
+console.log(sandboxes[0].metadata)
 ```
 ```python
 from e2b_code_interpreter import Sandbox
@@ -41,12 +41,12 @@ sandbox = Sandbox(
 )
 
 # List running sandboxes and access metadata.
-running_sandboxes = Sandbox.list()
+running_sandboxes = Sandbox.list(state=['running'])
 # Will print:
 # {
 #   'userId': '123',
 # }
-print(running_sandboxes[0].metadata)
+print(running_sandboxes.sandboxes[0].metadata)
 ```
 </CodeGroup>
 

apps/web/src/app/(docs)/docs/sandbox/persistence/page.mdx

@@ -128,6 +128,84 @@ print('Sandbox resumed', same_sbx.sandbox_id) # $HighlightLine
 ```
 </CodeGroup>
 
+## 4. Listing paused sandboxes
+You can list all paused sandboxes by calling the `Sandbox.list` method by supplying the `state` parameter.
+
+<CodeGroup>
+```js
+import { Sandbox } from '@e2b/code-interpreter'
+// or use Core: https://github.com/e2b-dev/e2b
+// import { Sandbox } from 'e2b'
+//
+// or use Desktop: https://github.com/e2b-dev/desktop
+// import { Sandbox } from '@e2b/desktop'
+
+// List all paused sandboxes
+const { sandboxes } = await Sandbox.list({ state: ['paused'] }) // $HighlightLine
+console.log('Paused sandboxes', sandboxes) // $HighlightLine
+```
+```python
+from e2b import Sandbox
+# or use Core: https://github.com/e2b-dev/e2b
+# from e2b import Sandbox
+#
+# or use Desktop: https://github.com/e2b-dev/desktop
+# from e2b_desktop import Sandbox
+
+# List all paused sandboxes
+sandboxes = Sandbox.list(state=['paused']) # $HighlightLine
+print('Paused sandboxes', sandboxes.sandboxes) # $HighlightLine
+```
+</CodeGroup>
+
+## 5. Removing paused sandboxes
+
+You can remove paused (and running!) sandboxes by calling the `kill` method on the Sandbox instance.
+
+<CodeGroup>
+```js
+import { Sandbox } from '@e2b/code-interpreter'
+// or use Core: https://github.com/e2b-dev/e2b
+// import { Sandbox } from 'e2b'
+//
+// or use Desktop: https://github.com/e2b-dev/desktop
+// import { Sandbox } from '@e2b/desktop'
+
+const sbx = await Sandbox.create()
+console.log('Sandbox created', sbx.sandboxId)
+
+// Pause the sandbox
+// You can save the sandbox ID in your database
+// to resume the sandbox later
+const sandboxId = await sbx.pause()
+
+// Remove the sandbox
+await sbx.kill() // $HighlightLine
+
+// Remove sandbox by id
+await Sandbox.kill(sandboxId) // $HighlightLine
+```
+```python
+from e2b import Sandbox
+# or use Core: https://github.com/e2b-dev/e2b
+# from e2b import Sandbox
+#
+# or use Desktop: https://github.com/e2b-dev/desktop
+# from e2b_desktop import Sandbox
+
+sbx = Sandbox()
+
+# Pause the sandbox
+sandbox_id = sbx.pause()
+
+# Remove the sandbox
+sbx.kill() # $HighlightLine
+
+# Remove sandbox by id
+Sandbox.kill(sandbox_id) # $HighlightLine
+```
+</CodeGroup>
+
 ## Sandbox's timeout
 When you resume a sandbox, the sandbox's timeout is reset to the default timeout of an E2B sandbox - 5 minutes.
 

apps/web/src/code/js/basics/metadata.js

@@ -10,7 +10,7 @@ await sandbox.keepAlive(60_000)
 
 // Later, can be even from another process
 // List all running sandboxes
-const runningSandboxes = await Sandbox.list()
+const runningSandboxes = await Sandbox.list({ state: ['running'] })
 // Find the sandbox by metadata
 const found = runningSandboxes.find(s => s.metadata?.userID === 'uniqueID')
 if (found) {

apps/web/src/code/python/basics/metadata.py

@@ -11,10 +11,10 @@
 
 # Later, can be even from another process
 # List all running sandboxes
-running_sandboxes = Sandbox.list()
+running_sandboxes = Sandbox.list(state=['running'])
 
 # Find the sandbox by metadata
-for running_sandbox in running_sandboxes:
+for running_sandbox in running_sandboxes.sandboxes:
     if running_sandbox.metadata.get("user_id", "") == 'uniqueID':
         sandbox = Sandbox.reconnect(running_sandbox.sandbox_id)
         break

packages/cli/src/commands/sandbox/kill.ts

@@ -3,6 +3,7 @@ import * as commander from 'commander'
 import { ensureAPIKey } from 'src/api'
 import { asBold } from 'src/utils/format'
 import * as e2b from 'e2b'
+import { SandboxInfo } from 'e2b'
 
 async function killSandbox(sandboxID: string, apiKey: string) {
   const killed = await e2b.Sandbox.kill(sandboxID, { apiKey })
@@ -17,7 +18,7 @@ export const killCommand = new commander.Command('kill')
   .description('kill sandbox')
   .argument(
     '[sandboxID]',
-    `kill the sandbox specified by ${asBold('[sandboxID]')}`,
+    `kill the sandbox specified by ${asBold('[sandboxID]')}`
   )
   .alias('kl')
   .option('-a, --all', 'kill all running sandboxes')
@@ -28,31 +29,30 @@ export const killCommand = new commander.Command('kill')
       if (!sandboxID && !all) {
         console.error(
           `You need to specify ${asBold('[sandboxID]')} or use ${asBold(
-            '-a/--all',
-          )} flag`,
+            '-a/--all'
+          )} flag`
         )
         process.exit(1)
       }
 
       if (all && sandboxID) {
         console.error(
           `You cannot use ${asBold('-a/--all')} flag while specifying ${asBold(
-            '[sandboxID]',
-          )}`,
+            '[sandboxID]'
+          )}`
         )
         process.exit(1)
       }
 
       if (all) {
-        const sandboxes = await e2b.Sandbox.list({ apiKey })
-
+        const { sandboxes } = await e2b.Sandbox.list({ apiKey })
         if (sandboxes.length === 0) {
-          console.log('No running sandboxes')
+          console.log('No sandboxes found')
           process.exit(0)
         }
 
         await Promise.all(
-          sandboxes.map((sandbox) => killSandbox(sandbox.sandboxId, apiKey)),
+          sandboxes.map((sandbox) => killSandbox(sandbox.sandboxId, apiKey))
         )
       } else {
         await killSandbox(sandboxID, apiKey)

packages/cli/src/commands/sandbox/list.ts

@@ -8,12 +8,19 @@ import { handleE2BRequestError } from '../../utils/errors'
 export const listCommand = new commander.Command('list')
   .description('list all running sandboxes')
   .alias('ls')
-  .action(async () => {
+  .option('-s, --state <state>', 'filter by state', (value) => value.split(','))
+  .option('-f, --filters <filters>', 'filter by metadata', (value) =>
+    value.replace(/,/g, '&')
+  )
+  .action(async (options) => {
     try {
-      const sandboxes = await listSandboxes()
+      const sandboxes = await listSandboxes({
+        state: options.state,
+        filters: options.filters,
+      })
 
       if (!sandboxes?.length) {
-        console.log('No running sandboxes.')
+        console.log('No sandboxes found')
       } else {
         const table = new tablePrinter.Table({
           title: 'Running sandboxes',
@@ -28,6 +35,7 @@ export const listCommand = new commander.Command('list')
             { name: 'alias', alignment: 'left', title: 'Alias' },
             { name: 'startedAt', alignment: 'left', title: 'Started at' },
             { name: 'endAt', alignment: 'left', title: 'End at' },
+            { name: 'state', alignment: 'left', title: 'State' },
             { name: 'cpuCount', alignment: 'left', title: 'vCPUs' },
             { name: 'memoryMB', alignment: 'left', title: 'RAM MiB' },
             { name: 'metadata', alignment: 'left', title: 'Metadata' },
@@ -39,6 +47,8 @@ export const listCommand = new commander.Command('list')
               sandboxID: `${sandbox.sandboxID}-${sandbox.clientID}`,
               startedAt: new Date(sandbox.startedAt).toLocaleString(),
               endAt: new Date(sandbox.endAt).toLocaleString(),
+              state:
+                sandbox.state.charAt(0).toUpperCase() + sandbox.state.slice(1), // capitalize
               metadata: JSON.stringify(sandbox.metadata),
             }))
             .sort(
@@ -81,13 +91,26 @@ export const listCommand = new commander.Command('list')
     }
   })
 
-export async function listSandboxes(): Promise<
-  e2b.components['schemas']['RunningSandbox'][]
+type ListSandboxesOptions = {
+  state?: e2b.components['schemas']['SandboxState'][]
+  filters?: string
+}
+
+export async function listSandboxes({
+  state,
+  filters,
+}: ListSandboxesOptions = {}): Promise<
+  e2b.components['schemas']['ListedSandbox'][]
 > {
   ensureAPIKey()
 
   const signal = connectionConfig.getSignal()
-  const res = await client.api.GET('/sandboxes', { signal })
+  const res = await client.api.GET('/sandboxes', {
+    params: {
+      query: { state, query: filters },
+    },
+    signal,
+  })
 
   handleE2BRequestError(res.error, 'Error getting running sandboxes')
 

packages/cli/src/commands/sandbox/logs.ts

@@ -31,7 +31,7 @@ export function waitForSandboxEnd(sandboxID: string) {
         break
       }
 
-      const response = await listSandboxes()
+      const response = await listSandboxes({ state: ['running'] })
       const sandbox = response.find(
         (s) => s.sandboxID === getShortID(sandboxID)
       )
@@ -153,7 +153,7 @@ export const logsCommand = new commander.Command('logs')
           console.log(`\nLogs for sandbox ${asBold(sandboxID)}:`)
         }
 
-        const isRunningPromise = listSandboxes()
+        const isRunningPromise = listSandboxes({ state: ['running'] })
           .then((r) => r.find((s) => s.sandboxID === getShortID(sandboxID)))
           .then((s) => !!s)
 

packages/cli/src/commands/sandbox/metrics.ts

@@ -66,7 +66,7 @@ export const metricsCommand = new commander.Command('metrics')
           console.log(`\nMetrics for sandbox ${asBold(sandboxID)}:`)
         }
 
-        const isRunningPromise = listSandboxes()
+        const isRunningPromise = listSandboxes({ state: ['running'] })
           .then((r) => r.find((s) => s.sandboxID === getShortID(sandboxID)))
           .then((s) => !!s)
 

packages/js-sdk/package.json

@@ -28,7 +28,7 @@
     "dev": "tsup --watch",
     "example": "tsx example.mts",
     "test": "vitest run",
-    "generate": "python ./../../spec/remove_extra_tags.py sandboxes templates && openapi-typescript ../../spec/openapi_generated.yml -x api_key --support-array-length --alphabetize --output src/api/schema.gen.ts",
+    "generate": "python ./../../spec/remove_extra_tags.py sandboxes templates && openapi-typescript ../../spec/openapi_generated.yml -x api_key --array-length --alphabetize --output src/api/schema.gen.ts",
     "generate-envd-api": "openapi-typescript ../../spec/envd/envd.yaml -x api_key --support-array-length --alphabetize --output src/envd/schema.gen.ts",
     "generate-ref": "./scripts/generate_sdk_ref.sh",
     "check-deps": "knip",
@@ -50,7 +50,7 @@
     "dotenv": "^16.4.5",
     "knip": "^5.17.3",
     "npm-check-updates": "^16.14.20",
-    "openapi-typescript": "^6.7.6",
+    "openapi-typescript": "^7.6.1",
     "playwright": "^1.48.0",
     "react": "^18.3.1",
     "tsup": "^8.0.2",

packages/js-sdk/src/api/index.ts

@@ -59,6 +59,12 @@ class ApiClient {
           Authorization: `Bearer ${config.accessToken}`,
         }),
       },
+      querySerializer: {
+        array: {
+          style: 'form',
+          explode: false,
+        },
+      },
     })
 
     if (config.logger) {

packages/js-sdk/src/sandbox/sandboxApi.ts

@@ -16,6 +16,21 @@ export interface SandboxListOpts extends SandboxApiOpts {
    * Filter the list of sandboxes by metadata, e.g. `{"key": "value"}`, if there are multiple filters they are combined with AND.
    */
   filters?: Record<string, string>
+
+  /**
+   * Filter the list of sandboxes by state.
+   */
+  state?: Array<'running' | 'paused'> | undefined
+
+  /**
+   * Number of sandboxes to return.
+   */
+  limit?: number
+
+  /**
+   * Token to the next page.
+   */
+  nextToken?: string
 }
 
 /**
@@ -46,6 +61,11 @@ export interface SandboxInfo {
    * Sandbox start time.
    */
   startedAt: Date
+
+  /**
+   * Sandbox state.
+   */
+  state: 'running' | 'paused'
 }
 
 export class SandboxApi {
@@ -94,41 +114,84 @@ export class SandboxApi {
    *
    * @returns list of running sandboxes.
    */
-  static async list(
-      opts?: SandboxListOpts): Promise<SandboxInfo[]> {
-    const config = new ConnectionConfig(opts)
+  static async list(opts: SandboxListOpts = {}): Promise<{
+    sandboxes: SandboxInfo[],
+    hasMoreItems: boolean,
+    nextToken: string | undefined,
+    iterator: AsyncGenerator<SandboxInfo>
+  }> {
+    const { filters, state, limit, nextToken, requestTimeoutMs } = opts
+    const config = new ConnectionConfig({ requestTimeoutMs })
     const client = new ApiClient(config)
 
     let query = undefined
-    if (opts?.filters) {
-      const encodedPairs: Record<string, string> = Object.fromEntries(Object.entries(opts.filters).map(([key, value]) => [encodeURIComponent(key),encodeURIComponent(value)]))
+    if (filters) {
+      const encodedPairs: Record<string, string> = Object.fromEntries(
+        Object.entries(filters).map(([key, value]) => [
+          encodeURIComponent(key),
+          encodeURIComponent(value),
+        ])
+      )
       query = new URLSearchParams(encodedPairs).toString()
     }
 
     const res = await client.api.GET('/sandboxes', {
-        params: {
-          query: {query},
+      params: {
+        query: {
+          query,
+          state,
+          limit,
+          nextToken,
         },
-      signal: config.getSignal(opts?.requestTimeoutMs),
+      },
+      signal: config.getSignal(requestTimeoutMs),
     })
 
     const err = handleApiError(res)
     if (err) {
       throw err
     }
 
-    return (
-      res.data?.map((sandbox: components['schemas']['RunningSandbox']) => ({
-        sandboxId: this.getSandboxId({
-          sandboxId: sandbox.sandboxID,
-          clientId: sandbox.clientID,
-        }),
-        templateId: sandbox.templateID,
-        ...(sandbox.alias && { name: sandbox.alias }),
-        metadata: sandbox.metadata ?? {},
-        startedAt: new Date(sandbox.startedAt),
-      })) ?? []
-    )
+    const nextPageToken = res.response.headers.get('x-next-token') || undefined
+    const hasMoreItems = !!nextPageToken
+
+    const sandboxes = (res.data ?? []).map(sandbox => ({
+      sandboxId: this.getSandboxId({
+        sandboxId: sandbox.sandboxID,
+        clientId: sandbox.clientID,
+      }),
+      templateId: sandbox.templateID,
+      ...(sandbox.alias && { name: sandbox.alias }),
+      metadata: sandbox.metadata ?? {},
+      startedAt: new Date(sandbox.startedAt),
+      state: sandbox.state,
+    }))
+
+    return {
+      sandboxes,
+      hasMoreItems,
+      nextToken: nextPageToken,
+      iterator: this.listIterator({ limit, nextToken: nextPageToken, filters, state, requestTimeoutMs })
+    }
+  }
+
+  private static async *listIterator(options: SandboxListOpts = {}): AsyncGenerator<SandboxInfo> {
+    let nextPage = true
+    let token = options.nextToken
+
+    while (nextPage) {
+      const { sandboxes, hasMoreItems, nextToken } = await this.list({
+        ...options,
+        nextToken: token,
+      })
+
+      nextPage = hasMoreItems
+      token = nextToken
+
+      for (const sandbox of sandboxes) {
+        yield sandbox
+      }
+    }
   }
 
   /**
@@ -207,13 +270,13 @@ export class SandboxApi {
   }
 
   /**
- * Pause the sandbox specified by sandbox ID.
- *
- * @param sandboxId sandbox ID.
- * @param opts connection options.
- *
- * @returns `true` if the sandbox got paused, `false` if the sandbox was already paused.
- */
+   * Pause the sandbox specified by sandbox ID.
+   *
+   * @param sandboxId sandbox ID.
+   * @param opts connection options.
+   *
+   * @returns `true` if the sandbox got paused, `false` if the sandbox was already paused.
+   */
   protected static async pauseSandbox(
     sandboxId: string,
     opts?: SandboxApiOpts
@@ -247,7 +310,6 @@ export class SandboxApi {
     return true
   }
 
-
   protected static async resumeSandbox(
     sandboxId: string,
     timeoutMs: number,
@@ -264,6 +326,7 @@ export class SandboxApi {
       },
       body: {
         timeout: this.timeoutToSeconds(timeoutMs),
+        autoPause: false,
       },
       signal: config.getSignal(opts?.requestTimeoutMs),
     })
@@ -305,6 +368,7 @@ export class SandboxApi {
         metadata: opts?.metadata,
         envVars: opts?.envs,
         timeout: this.timeoutToSeconds(timeoutMs),
+        autoPause: false,
       },
       signal: config.getSignal(opts?.requestTimeoutMs),
     })

packages/js-sdk/tests/api/kill.test.ts

@@ -6,8 +6,8 @@ import { Sandbox } from '../../src'
 sandboxTest.skipIf(isDebug)('kill existing sandbox', async ({ sandbox }) => {
   await Sandbox.kill(sandbox.sandboxId)
 
-  const list = await Sandbox.list()
-  expect(list.map(s => s.sandboxId)).not.toContain(sandbox.sandboxId)
+  const { sandboxes } = await Sandbox.list()
+  expect(sandboxes.map((s) => s.sandboxId)).not.toContain(sandbox.sandboxId)
 })
 
 sandboxTest.skipIf(isDebug)('kill non-existing sandbox', async () => {

packages/js-sdk/tests/api/list.test.ts

@@ -4,37 +4,212 @@ import { Sandbox } from '../../src'
 import { sandboxTest, isDebug } from '../setup.js'
 
 sandboxTest.skipIf(isDebug)('list sandboxes', async ({ sandbox }) => {
-  const sandboxes = await Sandbox.list()
+  const { sandboxes } = await Sandbox.list()
+
   assert.isAtLeast(sandboxes.length, 1)
   assert.include(
     sandboxes.map((s) => s.sandboxId),
     sandbox.sandboxId
   )
-
-  // Check that sandboxes are sorted by startedAt in descending order (newest first)
-  for (let i = 0; i < sandboxes.length - 1; i++) {
-    assert.isAtLeast(
-      new Date(sandboxes[i + 1].startedAt).getTime(),
-      new Date(sandboxes[i].startedAt).getTime(),
-      'Sandboxes should be sorted by startedAt in descending order'
-    )
-  }
 })
 
 sandboxTest.skipIf(isDebug)('list sandboxes with filter', async () => {
   const uniqueId = Date.now().toString()
-  // Create an extra sandbox with a uniqueId
-  const extraSbx = await Sandbox.create({ })
+  const extraSbx = await Sandbox.create({ metadata: { uniqueId } })
+
   try {
-    const sbx = await Sandbox.create({metadata: {uniqueId: uniqueId}})
+    const { sandboxes } = await Sandbox.list({ filters: { uniqueId } })
+
+    assert.equal(sandboxes.length, 1)
+    assert.equal(sandboxes[0].sandboxId, extraSbx.sandboxId)
+  } finally {
+    await extraSbx.kill()
+  }
+})
+
+sandboxTest.skipIf(isDebug)('list paused sandboxes', async ({ sandbox }) => {
+  const pausedSandbox = await sandbox.pause()
+  const pausedSandboxId = pausedSandbox.split('-')[0] + '-' + '00000000'
+  const { sandboxes } = await Sandbox.list({ state: ['paused'] })
+
+  assert.isAtLeast(sandboxes.length, 1)
+  assert.include(
+    sandboxes.map((s) => s.sandboxId),
+    pausedSandboxId
+  )
+})
+
+sandboxTest.skipIf(isDebug)('list running sandboxes', async ({ sandbox }) => {
+  const extraSbx = await Sandbox.create()
+  const { sandboxes } = await Sandbox.list({ state: ['running'] })
+
+  assert.isAtLeast(sandboxes.length, 1)
+  assert.include(
+    sandboxes.map((s) => s.sandboxId),
+    extraSbx.sandboxId
+  )
+})
+
+sandboxTest.skipIf(isDebug)(
+  'list sandboxes with limit',
+  async ({ sandbox }) => {
+    const { sandboxes } = await Sandbox.list({ limit: 1 })
+    assert.equal(sandboxes.length, 1)
+    assert.include(
+      sandboxes.map((s) => s.sandboxId),
+      sandbox.sandboxId
+    )
+  }
+)
+
+sandboxTest.skipIf(isDebug)(
+  'paginate running sandboxes',
+  async ({ sandbox }) => {
+    const extraSbx = await Sandbox.create()
+
     try {
-      const sandboxes = await Sandbox.list({filters: {uniqueId}})
+      const { sandboxes, hasMoreItems, nextToken } = await Sandbox.list({
+        state: ['running'],
+        limit: 1,
+      })
+
+      // check first page
       assert.equal(sandboxes.length, 1)
-      assert.equal(sandboxes[0].sandboxId, sbx.sandboxId)
+      assert.equal(sandboxes[0].state, 'running')
+      assert.isTrue(hasMoreItems)
+      assert.notEqual(nextToken, undefined)
+
+      // new sandbox should be on first page
+      assert.include(
+        sandboxes.map((s) => s.sandboxId),
+        extraSbx.sandboxId
+      )
+
+      // fetch second page
+      const {
+        sandboxes: sandboxes2,
+        hasMoreItems: hasMoreItems2,
+        nextToken: nextToken2,
+      } = await Sandbox.list({
+        state: ['running'],
+        nextToken: nextToken,
+        limit: 1,
+      })
+
+      // check second page
+      assert.equal(sandboxes2.length, 1)
+      assert.equal(sandboxes2[0].state, 'running')
+      assert.isFalse(hasMoreItems2)
+      assert.equal(nextToken2, undefined)
+
+      // past sandbox should be on second page
+      assert.include(
+        sandboxes2.map((s) => s.sandboxId),
+        sandbox.sandboxId
+      )
     } finally {
-      await sbx.kill()
+      await extraSbx.kill()
     }
-  } finally {
-    await extraSbx.kill()
   }
-})
+)
+
+sandboxTest.skipIf(isDebug)(
+  'paginate paused sandboxes',
+  async ({ sandbox }) => {
+    // pause the current sandbox
+    await sandbox.pause()
+
+    // create a new sandbox
+    const extraSbx = await Sandbox.create()
+    await extraSbx.pause()
+
+    const { sandboxes, hasMoreItems, nextToken } = await Sandbox.list({
+      state: ['paused'],
+      limit: 1,
+    })
+
+    // check first page
+    assert.equal(sandboxes.length, 1)
+    assert.equal(sandboxes[0].state, 'paused')
+    assert.isTrue(hasMoreItems)
+    assert.notEqual(nextToken, undefined)
+
+    // new sandbox should be on first page
+    assert.include(
+      sandboxes.map((s) => s.sandboxId),
+      extraSbx.sandboxId
+    )
+
+    // fetch second page
+    const {
+      sandboxes: sandboxes2,
+      hasMoreItems: hasMoreItems2,
+      nextToken: nextToken2,
+    } = await Sandbox.list({
+      state: ['paused'],
+      nextToken: nextToken,
+      limit: 1,
+    })
+
+    // check second page
+    assert.equal(sandboxes2.length, 1)
+    assert.equal(sandboxes2[0].state, 'paused')
+    assert.isFalse(hasMoreItems2)
+    assert.equal(nextToken2, undefined)
+
+    // past sandbox should be on second page
+    assert.include(
+      sandboxes2.map((s) => s.sandboxId),
+      sandbox.sandboxId
+    )
+  }
+)
+
+sandboxTest.skipIf(isDebug)(
+  'paginate paused and running sandboxes',
+  async ({ sandbox }) => {
+    // create a new sandbox
+    const extraSbx = await Sandbox.create()
+    await extraSbx.pause()
+
+    const { sandboxes, hasMoreItems, nextToken } = await Sandbox.list({
+      state: ['paused', 'running'],
+      limit: 1,
+    })
+
+    // check first page
+    assert.equal(sandboxes.length, 1)
+    assert.equal(sandboxes[0].state, 'paused')
+    assert.isTrue(hasMoreItems)
+    assert.notEqual(nextToken, undefined)
+
+    // new sandbox should be on first page
+    assert.include(
+      sandboxes.map((s) => s.sandboxId),
+      extraSbx.sandboxId
+    )
+
+    // fetch second page
+    const {
+      sandboxes: sandboxes2,
+      hasMoreItems: hasMoreItems2,
+      nextToken: nextToken2,
+    } = await Sandbox.list({
+      state: ['paused'],
+      nextToken: nextToken,
+      limit: 1,
+    })
+
+    // check second page
+    assert.equal(sandboxes2.length, 1)
+    assert.equal(sandboxes2[0].state, 'running')
+    assert.isFalse(hasMoreItems2)
+    assert.equal(nextToken2, undefined)
+
+    // past sandbox should be on second page
+    assert.include(
+      sandboxes2.map((s) => s.sandboxId),
+      sandbox.sandboxId
+    )
+  }
+)

packages/js-sdk/tests/sandbox/create.test.ts

@@ -21,10 +21,9 @@ test.skipIf(isDebug)('metadata', async () => {
   }
 
   const sbx = await Sandbox.create(template, { timeoutMs: 5_000, metadata })
-
   try {
-    const sbxs = await Sandbox.list()
-    const sbxInfo = sbxs.find((s) => s.sandboxId === sbx.sandboxId)
+    const { sandboxes } = await Sandbox.list()
+    const sbxInfo = sandboxes.find((s) => s.sandboxId === sbx.sandboxId)
 
     assert.deepEqual(sbxInfo?.metadata, metadata)
   } finally {

packages/js-sdk/tests/sandbox/kill.test.ts

@@ -6,6 +6,6 @@ import { sandboxTest, isDebug } from '../setup.js'
 sandboxTest.skipIf(isDebug)('kill', async ({ sandbox }) => {
   await sandbox.kill()
 
-  const list = await Sandbox.list()
-  expect(list.map(s => s.sandboxId)).not.toContain(sandbox.sandboxId)
+  const { sandboxes } = await Sandbox.list()
+  expect(sandboxes.map((s) => s.sandboxId)).not.toContain(sandbox.sandboxId)
 })

packages/python-sdk/Makefile

@@ -1,9 +1,9 @@
 generate-api:
 	python ./../../spec/remove_extra_tags.py sandboxes
-	openapi-python-client generate --output-path e2b/api/api --overwrite --path ../../spec/openapi_generated.yml
+	openapi-python-client generate --output-path e2b/api/api --overwrite --path ../../spec/openapi_generated.yml --config openapi-generator.yml
 	rm -rf e2b/api/client
 	mv e2b/api/api/e2b_api_client e2b/api/client
 	rm -rf e2b/api/api
 
 init:
-	pip install openapi-python-client
+	pip install openapi-python-client==0.23.1