> ## 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.

# Create a sandbox

> Create a sandbox from the default or a named template, set the timeout, environment variables and metadata, and find the sandbox again by its metadata.

Create a sandbox with one SDK call or one `ppio sandbox create` command. The call takes a template name or ID and options such as the timeout, environment variables and metadata (Custom key-value information attached to a sandbox.). Metadata set at creation is what list filters match later.

> [!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).

## Create from the default template

Call `create()` without arguments to start a sandbox from the default `base` template.

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

ppio = PPIO()
sandbox = ppio.sandbox.create()

print("Sandbox ID:", sandbox.sandbox_id)

sandbox.kill()
```

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

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

console.log('Sandbox ID:', sandbox.sandboxId)

await sandbox.kill()
```

```bash CLI theme={null}
# Create a sandbox from the base template and connect a terminal (alias: sandbox cr)
ppio sandbox create base

# Create without connecting a terminal (detached), returns the sandbox ID
ppio sandbox create base -d
```

## Create from a template

Pass the name or ID of an existing template as the first argument to create the sandbox from that template instead of `base`.

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

ppio = PPIO()
sandbox = ppio.sandbox.create(
    "my-python-app",           # template name or ID
    timeout=300,               # seconds, optional
    metadata={"env": "demo"},
    envs={"KEY": "value"},
)

print("Sandbox ID:", sandbox.sandbox_id)

# Use it.
result = sandbox.commands.run("python3 --version")
print(result.stdout)

sandbox.kill()
```

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

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create('my-python-app', {
  timeoutMs: 300_000, // milliseconds, optional
  metadata: { env: 'demo' },
  envs: { KEY: 'value' },
})

console.log('Sandbox ID:', sandbox.sandboxId)

// Use it.
const result = await sandbox.commands.run('python3 --version')
console.log(result.stdout)

await sandbox.kill()
```

```bash CLI theme={null}
# Create a sandbox from a specific template (by name or template ID)
ppio sandbox create my-python-app

# Detached (no terminal), prints the new sandbox ID
ppio sandbox create my-python-app -d
```

### Use a context manager in Python

Use a context manager for automatic cleanup.

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

ppio = PPIO()

with ppio.sandbox.create("my-python-app") as sandbox:
    print(sandbox.commands.run("echo hello").stdout)
# Automatically killed when exiting the with block.
```

## Create options

The options below are the ones this page uses. Pass them as arguments in Python and as one options object in Node.js.

> [tab] Python
>
> **template** `string` (default: base)
>
> First argument: template name or ID.
>
> **timeout** `number`
>
> Sandbox timeout in seconds. Optional.
>
> **metadata** `object`
>
> Key-value pairs stored with the sandbox, such as an ID from the calling application.
>
> **envs** `object`
>
> Environment variables available to commands in the sandbox.

> [tab] Node.js
>
> **template** `string` (default: base)
>
> First argument: template name or ID.
>
> **timeoutMs** `number`
>
> Sandbox timeout in milliseconds. Optional.
>
> **metadata** `object`
>
> Key-value pairs stored with the sandbox, such as an ID from the calling application.
>
> **envs** `object`
>
> Environment variables available to commands in the sandbox.

## Set sandbox environment variables

Set environment variables when creating the sandbox. A single command can override or append them.

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

ppio = PPIO()
sandbox = ppio.sandbox.create(
    "my-python-app",
    envs={
        "API_KEY": "secret-123",
        "LOG_LEVEL": "debug",
        "PORT": "8000",
    },
)

# Verify.
result = sandbox.commands.run("echo $API_KEY")
print(result.stdout)   # secret-123

# Override or append envs on a single command.
result = sandbox.commands.run("echo $LOG_LEVEL", envs={"LOG_LEVEL": "info"})
print(result.stdout)   # info

sandbox.kill()
```

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

const ppio = new PPIO()

// Set environment variables when creating the sandbox.
const sandbox = await ppio.sandbox.create('my-python-app', {
  envs: {
    API_KEY: 'secret-123',
    LOG_LEVEL: 'debug',
    PORT: '8000',
  },
})

// Verify.
let result = await sandbox.commands.run('echo $API_KEY')
console.log(result.stdout) // secret-123

// You can also override/append envs on a single command.
result = await sandbox.commands.run('echo $LOG_LEVEL', {
  envs: { LOG_LEVEL: 'info' },
})
console.log(result.stdout) // info

await sandbox.kill()
```

## Attach metadata

Metadata attaches custom key-value information to a sandbox. Common uses:

* Connecting a sandbox to a user session.
* Saving custom user-related data for a sandbox, such as API keys.
* Linking a sandbox to a user ID so it can be reconnected later.

Metadata is set when the sandbox is created. Listing active sandboxes with `ppio.sandbox.list()` returns it later.

Listing accepts a metadata filter and a state filter. Multiple conditions are combined with AND.

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

ppio = PPIO()
sandbox = ppio.sandbox.create(metadata={"userId": "123"})

# Retrieve active sandboxes and inspect their metadata.
page = ppio.sandbox.list()
active = page.next_items()

print(active[0].metadata)
# Example output:
# {"userId": "123"}

paginator = ppio.sandbox.list(
    query=SandboxQuery(metadata={"userId": "123"}, state=[SandboxState.RUNNING]),
)
for item in paginator.next_items():
    print(item.sandbox_id, item.state, item.metadata)

sandbox.kill()
```

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

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create({ metadata: { userId: '123' } })

// Retrieve active sandboxes and inspect their metadata.
const page = await ppio.sandbox.list()
const active = await page.nextItems()

console.log(active[0].metadata)
// Example output:
// { userId: '123' }

const paginator = ppio.sandbox.list({
  query: { metadata: { userId: '123' }, state: ['running'] },
})
for (const item of await paginator.nextItems()) {
  console.log(item.sandboxId, item.state, item.metadata)
}

await sandbox.kill()
```


## Related topics

- [Create your first sandbox](https://docs.ppio.ai/sandbox/quickstart.md)
- [Manage sandboxes in the PPIO console](https://docs.ppio.ai/sandbox/console.md)
- [Set or extend a sandbox timeout](https://docs.ppio.ai/sandbox/timeout.md)


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