> For the complete documentation index, see [llms.txt](https://docs.ai.neevcloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ai.neevcloud.com/agentic-studio/overview/sandbox-management/create-pause-delete-sandboxes.md).

# Create, Pause, Delete Sandboxes

Sandbox can be created, paused, resumed, and deleted based on your workload needs.

You can spin up a new sandbox, pause it to stop billing while preserving its state, resume it when needed, and permanently delete it when it is no longer required.

## Create a Sandbox

### Console

1. Navigate to AI Agents → Sandboxes from the left sidebar
2. Click on **Create Sandbox +**
3. A configuration panel will open on the right side

**Sandbox Name**

* An auto-generated name is provided (e.g., `my-sandbox-aj9b`)
* You can rename it to something more descriptive

**Template**

Choose the base image for your sandbox:

* `ubuntu-26.04-dev` - Standard, with development tooling (the default)
* `debian-12-minimal` - Standard
* `ubuntu-24.04-minimal` - Standard
* `ubuntu-26.04-minimal` - Standard
* `ubuntu-26.04-systemd` - Standard
* `ubuntu-26.04-vnc` - Browser

**Region**

* Select where your sandbox will run
* Available region: Indore (`as-south-1`)

**Allow Internet Access**

* Disabled by default, and you can change it later on the running sandbox (see [Internet Access and Egress](/agentic-studio/overview/security-and-monitoring/internet-access.md))
* Enable only if your sandbox needs outbound HTTP requests (e.g., APIs, external services)
* For finer control than a simple on/off toggle - such as allowing only specific hosts, ports, or protocols - configure egress via the SDK (see [Fine-Grained Network Egress](#fine-grained-network-egress) below)

### Resources (Optional)

Use the sliders to configure compute resources for your sandbox:

| Resource | Default | Range       |
| -------- | ------- | ----------- |
| vCPUs    | 1       | 0.5 – 8     |
| Memory   | 2 GB    | 1 – 16 GB   |
| Disk     | 10 GB   | 10 – 100 GB |

The estimated hourly cost updates in real time as you adjust the sliders. For example, the default configuration of 1 vCPU · 2 GB RAM · 10 GB disk is priced at ₹11.86/hr.

### Environment Variables (Optional)

Click **Add +** to inject key-value pairs into the sandbox at creation time. Use this to pass API keys, configuration flags, or any environment-specific values your agent code needs at startup.

Once you have configured all fields, click **Create Sandbox**.

**Note:** Sandbox provisioning is asynchronous. The sandbox will initially appear as Pending and automatically transition to Ready once provisioning is complete. Do not attempt to connect to or run commands on the sandbox while it is in the Pending state.

### SDK

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
import { Neev } from "@neevcloud/sdk";

const neev = new Neev({
  apiKey: process.env.NEEV_API_KEY,
  orgId: process.env.NEEV_ORG_ID,
  projectId: process.env.NEEV_PROJECT_ID,
});

const sandbox = await neev.sandboxes.create({
  name: "my-agent",
  region: "as-south-1",
  sandbox_template_id: "sb-ubuntu-26-04-minimal",
});

await sandbox.waitUntilReady();
console.log(sandbox.id, sandbox.phase); // Ready
```

{% endtab %}

{% tab title="Python" %}

```python
from neevai import NeevAI

with NeevAI() as client:
    sandbox = client.sandboxes.create({
        "name": "my-agent",
        "region": "as-south-1",
        "sandbox_template_id": "sb-ubuntu-26-04-minimal",
    })
    sandbox.wait_until_ready()
    print(sandbox.id, sandbox.phase)  # Ready
```

{% endtab %}
{% endtabs %}

To list all your sandboxes:

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
const page = await neev.sandboxes.list({ limit: 50 });
```

{% endtab %}

{% tab title="Python" %}

```python
page = client.sandboxes.list(limit=50)
```

{% endtab %}
{% endtabs %}

To get a specific sandbox by ID:

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
const sandbox = await neev.sandboxes.get("sandbox-id");
```

{% endtab %}

{% tab title="Python" %}

```python
sandbox = client.sandboxes.get("sandbox-id")
```

{% endtab %}
{% endtabs %}

### Naming Rules

If you provide your own `name` instead of letting the platform generate one, it must be a valid DNS-style name: lowercase letters, numbers, and hyphens only, starting with a letter, ending with a letter or number, and no longer than 63 characters (for example `my-agent`, not `My_Agent!`).

### Starting from a Custom Image or a Snapshot

Besides a platform template, you can start a sandbox from two other sources. Provide exactly one of `sandbox_template_id`, `image`, or `restore` - they're mutually exclusive:

| Option                | What it does                                                                                                                                                                                                     |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sandbox_template_id` | The default path - start from a platform-managed template (see [Sandbox Templates (API)](/agentic-studio/overview/sandbox-management/sandbox-templates.md))                                                      |
| `image`               | Bring your own public OCI image, with an explicit tag or digest, up to 3 GB                                                                                                                                      |
| `restore`             | Start from a previously captured snapshot instead of a fresh image - see [Snapshots](/agentic-studio/overview/sandbox-management/snapshots.md). `from_snapshot` is the older, deprecated name for the same field |

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
// Bring your own image instead of a platform template
const sandbox = await neev.sandboxes.create({
  name: "my-agent",
  region: "as-south-1",
  image: "docker.io/library/ubuntu:24.04",
});
```

{% endtab %}

{% tab title="Python" %}

```python
# Bring your own image instead of a platform template
sandbox = client.sandboxes.create({
    "name": "my-agent",
    "region": "as-south-1",
    "image": "docker.io/library/ubuntu:24.04",
})
```

{% endtab %}
{% endtabs %}

If you omit `sandbox_template_id`, `image`, and `restore` altogether, the sandbox uses the platform default template, `sb-ubuntu-26-04-dev`.

### Fine-Grained Network Egress

The console's "Allow Internet Access" toggle covers the common case. Via the SDK, you can instead restrict outbound traffic to specific hosts, ports, and protocols - useful when your agent only needs to reach your own API, not the open internet:

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
const sandbox = await neev.sandboxes.create({
  name: "my-agent",
  region: "as-south-1",
  sandbox_template_id: "sb-ubuntu-26-04-minimal",
  egress: {
    mode: "allow_list",
    allow: [
      { host: "api.mycompany.com", ports: [443], protocol: "TCP" },
    ],
  },
});
```

{% endtab %}

{% tab title="Python" %}

```python
sandbox = client.sandboxes.create({
    "name": "my-agent",
    "region": "as-south-1",
    "sandbox_template_id": "sb-ubuntu-26-04-minimal",
    "egress": {
        "mode": "allow_list",
        "allow": [
            {"host": "api.mycompany.com", "ports": [443], "protocol": "TCP"},
        ],
    },
})
```

{% endtab %}
{% endtabs %}

`mode` is `deny_all` (the default) or `allow_list`. To open full internet access instead of allow-listing specific hosts, set `allow_internet: true` - this is an explicit escape hatch, so use it deliberately rather than as a default.

## Resize a Sandbox

You can resize a running sandbox's CPU and memory in place, without restarting it or losing any state. Only the fields you provide are changed - anything you omit stays the same. Disk size cannot be resized in place; create a new sandbox if you need more disk.

### API

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X PATCH "https://api.ai.neevcloud.com/agent/api/v1beta1/orgs/$ORG_ID/projects/$PROJECT_ID/sandboxes/$SANDBOX_ID" \
  -H "Authorization: Bearer $NEEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resources": {"cpu": 2, "memory_gb": 4}}'
```

{% endtab %}
{% endtabs %}

**Use this when:** your agent workload turns out to need more headroom than you initially provisioned, and you'd rather resize in place than recreate the sandbox and lose its current state.

## Pause a Sandbox

Pausing a sandbox stops the compute without deleting the sandbox or its data. Its memory and files are saved, so running processes, installed packages, and environment state all come back on resume. Billing stops while the sandbox is paused.

Use Pause when:

* You are done with the sandbox for now but plan to resume work later
* You want to stop incurring hourly charges without losing your working state
* You need to free up compute resources temporarily

### Console

1. Go to AI Agents → Sandboxes
2. Click on the sandbox you want to pause
3. Click the **Pause** button in the top-right of the detail panel

The sandbox status will update to Paused.

### SDK

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
// Pause using the sandbox handle
await sandbox.pause();

// Or pause directly by ID
await neev.sandboxes.pause("sandbox-id");
```

{% endtab %}

{% tab title="Python" %}

```python
# Pause using the sandbox handle
sandbox.pause()

# Or pause directly by ID
client.sandboxes.pause("sandbox-id")
```

{% endtab %}
{% endtabs %}

## Resume a Sandbox

Resuming a paused sandbox restarts the compute and returns it to the Ready state. Its files and running processes are exactly as you left them.

### Console

1. Go to AI Agents → Sandboxes
2. Click on the paused sandbox
3. Click the **Resume** button in the top-right of the detail panel

### SDK

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
// Resume using the sandbox handle
await sandbox.resume();

// Or resume directly by ID
await neev.sandboxes.resume("sandbox-id");
```

{% endtab %}

{% tab title="Python" %}

```python
# Resume using the sandbox handle
sandbox.resume()

# Or resume directly by ID
client.sandboxes.resume("sandbox-id")
```

{% endtab %}
{% endtabs %}

## Delete a Sandbox

Deleting a sandbox permanently removes it along with all its data, files, and environment state. This action cannot be undone.

**Warning:** Deleting a sandbox also deletes all of its snapshots, so taking a snapshot first does not preserve anything. To keep its state, fork it into a new sandbox before deleting it (see [Undo and Duplicate](/agentic-studio/overview/sandbox-management/undo-and-duplicate.md)). Once deleted, there is no way to recover the sandbox or its data.

### Console

1. Go to AI Agents → Sandboxes
2. Click on the sandbox you want to delete
3. Click the **Delete** button in the top-right of the detail panel
4. Confirm the deletion when prompted

### SDK

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
// Delete using the sandbox handle
await sandbox.delete();

// Or delete directly by ID
await neev.sandboxes.delete("sandbox-id");
```

{% endtab %}

{% tab title="Python" %}

```python
# Delete using the sandbox handle
sandbox.delete()

# Or delete directly by ID
client.sandboxes.delete("sandbox-id")
```

{% endtab %}
{% endtabs %}

## Sandbox Actions Summary

| Action     | What it does                                                 | Billing impact                              | Data preserved                             |
| ---------- | ------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------ |
| **Create** | Provisions a new sandbox from a template, image, or snapshot | Billing starts when status is Ready         | N/A                                        |
| **Resize** | Changes CPU/memory on a running sandbox in place             | Billing reflects the new size going forward | Yes - no restart, nothing is lost          |
| **Pause**  | Stops compute, saves memory and files                        | Billing pauses                              | Yes - files and running processes are kept |
| **Resume** | Restarts a paused sandbox                                    | Billing resumes                             | Yes - picks up from where you left off     |
| **Delete** | Permanently removes sandbox, its snapshots, and all data     | Billing stops immediately                   | No - all data is permanently lost          |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ai.neevcloud.com/agentic-studio/overview/sandbox-management/create-pause-delete-sandboxes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.