> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to a running sandbox

> Find the ID of a running sandbox with the SDK, then connect to it with ppio.sandbox.connect() from another function invocation, session, or process.

`ppio.sandbox.connect()` attaches the SDK to a running or paused sandbox and continues controlling it. Connect when work resumes somewhere else: another serverless function invocation, a user's web app session, long-running work to reconnect to, or a paused sandbox after a short period of inactivity.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## Connect to a sandbox

Before connecting, the sandbox ID is required. Get it with `ppio.sandbox.list()`, then pass it to `ppio.sandbox.connect()`.

**1. Find the sandbox ID**

List the sandboxes in the Running state and take the ID of the first one.

```python Python theme={null}
# --- Get the sandbox ID ---
# Get all running sandboxes
running_sandboxes_paginator = ppio.sandbox.list(query=SandboxQuery(state=[SandboxState.RUNNING]))

running_sandboxes = running_sandboxes_paginator.next_items()
if len(running_sandboxes) == 0:
    raise Exception("No running sandboxes found")
running_sandbox_id = running_sandboxes[0].sandbox_id
```

```javascript Node.js theme={null}
// --- Get the sandbox ID ---
// Get all running sandboxes
const runningSandboxesPaginator = await ppio.sandbox.list({
  query: {
    state: ['running'],
  },
})

const runningSandboxes = await runningSandboxesPaginator.nextItems()
if (runningSandboxes.length === 0) {
  throw new Error('No running sandboxes found')
}
const runningSandboxId = runningSandboxes[0].sandboxId
```

**2. Connect to the sandbox**

Pass the ID to `connect()`, then use the sandbox as usual.

```python Python theme={null}
# --- Connect to the sandbox ---
sandbox = ppio.sandbox.connect(running_sandbox_id)
print("connected to sandbox: ", sandbox.sandbox_id)
```

```javascript Node.js theme={null}
// --- Connect to the sandbox ---
const sandbox = await ppio.sandbox.connect(runningSandboxId)
console.log('connected to sandbox: ', sandbox.sandboxId)
```

### Full example

In the CLI example, `<sandbox-id>` is the sandbox ID.

```python Python theme={null}
from ppio_sandbox import PPIO, SandboxQuery, SandboxState

ppio = PPIO()

# --- Get the sandbox ID ---
# Get all running sandboxes
running_sandboxes_paginator = ppio.sandbox.list(query=SandboxQuery(state=[SandboxState.RUNNING]))

running_sandboxes = running_sandboxes_paginator.next_items()
if len(running_sandboxes) == 0:
    raise Exception("No running sandboxes found")
running_sandbox_id = running_sandboxes[0].sandbox_id

# --- Connect to the sandbox ---
sandbox = ppio.sandbox.connect(running_sandbox_id)
print("connected to sandbox: ", sandbox.sandbox_id)

# Now you can use the sandbox as usual
# ...

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

// --- Get the sandbox ID ---
// Get all running sandboxes
const runningSandboxesPaginator = await ppio.sandbox.list({
  query: {
    state: ['running'],
  },
})

const runningSandboxes = await runningSandboxesPaginator.nextItems()
if (runningSandboxes.length === 0) {
  throw new Error('No running sandboxes found')
}
const runningSandboxId = runningSandboxes[0].sandboxId

// --- Connect to the sandbox ---
const sandbox = await ppio.sandbox.connect(runningSandboxId)
console.log('connected to sandbox: ', sandbox.sandboxId)

// Now you can use the sandbox as usual
// ...

await sandbox.kill()
```

```bash CLI theme={null}
# Attach an interactive terminal to a running sandbox (alias: sandbox cn)
ppio sandbox connect <sandbox-id>
```


## Related topics

- [ppio sandbox connect](https://docs.ppio.ai/sandbox/cli/connect.md)
- [Connect a sandbox to a VPN with OpenVPN](https://docs.ppio.ai/sandbox/openvpn.md)
- [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.