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

# Create Sandbox

## Create Sandbox

The simplest way to create a sandbox is to call `novita.sandbox.create()` without any arguments.

```js JavaScript & TypeScript icon="js" theme={"system"}
import 'dotenv/config'
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()

await sandbox.kill()
```

```python Python icon="python" theme={"system"}
from dotenv import load_dotenv
from novita_sandbox import Novita

load_dotenv()

novita = Novita()
sandbox = novita.sandbox.create()

sandbox.kill()
```

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

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

## From Template

You can create a sandbox from a template by passing the template name or ID.

```python Python icon="python" theme={"system"}
from dotenv import load_dotenv
from novita_sandbox import Novita

load_dotenv()

novita = Novita()

# Create a sandbox from a template name or template ID.
sandbox = novita.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()
```

Use a context manager for automatic cleanup:

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()

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

```js JavaScript & TypeScript icon="js" theme={"system"}
import 'dotenv/config'
import { Novita } from 'novita-sandbox'

const novita = new Novita()

// Create a sandbox from a template name or template ID.
const sandbox = await novita.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 icon="terminal" theme={"system"}
# Create a sandbox from a specific template (by name or template ID)
novita sandbox create <template>

# Detached (no terminal), prints the new sandbox ID
novita sandbox create <template> -d
```

## Environment Variables

You can set environment variables when creating a sandbox, and override or append them on a single command.

```python Python icon="python" theme={"system"}
from dotenv import load_dotenv
from novita_sandbox import Novita

load_dotenv()

novita = Novita()

# Set environment variables when creating the sandbox.
sandbox = novita.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

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

sandbox.kill()
```

```js JavaScript & TypeScript icon="js" theme={"system"}
import 'dotenv/config'
import { Novita } from 'novita-sandbox'

const novita = new Novita()

// Set environment variables when creating the sandbox.
const sandbox = await novita.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()
```

## Metadata

Sandbox metadata lets you attach custom key-value information to a sandbox.

Common uses include:

* 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 provided when the sandbox is created. Later, it can be read when listing active sandboxes with `novita.sandbox.list()`. Sandboxes can also be filtered using metadata when listing.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita, SandboxState } from 'novita-sandbox'

const novita = new Novita()

// Start a sandbox and attach custom metadata.
const sbx = await novita.sandbox.create({
  metadata: {
    userId: '123',
  },
})

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

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

// Filter by metadata.
let sandboxes = await novita.sandbox.list({
  query: { metadata: { env: 'demo' } },
})

// Combine metadata and state filters (multiple conditions are AND).
sandboxes = await novita.sandbox.list({
  query: {
    metadata: { env: 'demo' },
    state: [SandboxState.RUNNING],
  },
})

for (const sandbox of sandboxes) {
  console.log(sandbox.sandboxId, sandbox.state, sandbox.metadata)
}
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita, SandboxQuery, SandboxState

novita = Novita()

# Start a sandbox and attach custom metadata.
sbx = novita.sandbox.create(
    metadata={
        "userId": "123",
    },
)

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

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

# Filter by metadata.
sandboxes = novita.sandbox.list(
    query=SandboxQuery(metadata={"env": "demo"})
)

# Combine metadata and state filters (multiple conditions are AND).
sandboxes = novita.sandbox.list(
    query=SandboxQuery(
        metadata={"env": "demo"},
        state=[SandboxState.RUNNING],
    )
)

for sandbox in sandboxes:
    print(sandbox.sandbox_id, sandbox.state, sandbox.metadata)
```


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