Adds 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/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) # $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,7 +11,7 @@
 
 # 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:

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

@@ -17,7 +17,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,17 +28,17 @@ 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)
       }
@@ -47,12 +47,12 @@ export const killCommand = new commander.Command('kill')
         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) {