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')