> 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/getting-started.md).

# Getting Started

## What is a Sandbox

A sandbox is an isolated, on-demand compute environment where you can run AI agents and execute code safely. Each sandbox is fully provisioned with the resources you configure and operates independently from your local machine and production systems.

Sandbox allow you to quickly spin up environments, experiment with workloads, and manage execution without handling infrastructure setup.

## Prerequisites

* A NeevCloud account
* Your API key, Organization ID, and Project ID from the NeevCloud console
* Node.js 18+, Bun, or Deno installed (for TypeScript/JavaScript)
* Python 3.10+ installed (for Python)

## How Sandbox Work

A sandbox is a secure, isolated compute environment that runs on NeevCloud infrastructure. Each sandbox is provisioned from a base template, assigned dedicated CPU, memory, and disk resources, and runs in a single region.

There are a few important behaviors to understand before you start:

* **Provisioning is asynchronous.** When you create a sandbox, it does not start immediately. It first enters a Pending state while the platform provisions the environment. It automatically transitions to Ready once provisioning is complete. Always wait for the sandbox to be Ready before running any commands or file operations on it.
* **Billing is compute-based.** You are billed for the time your sandbox is in the Ready state. If you need to stop billing temporarily without losing your work, you can Pause the sandbox. Pausing halts compute billing while preserving the disk and all files on it.
* **Internet access is off by default.** A sandbox cannot reach the internet unless you explicitly enable internet access during creation. Enable it only if your agent workload needs to make outbound HTTP calls.

## Sandbox Lifecycle

* **Pending** – Sandbox is being provisioned. Wait for it to become Ready before connecting
* **Ready** – Sandbox is running and reachable. Billing is active
* **Paused** – Compute is stopped while disk state is preserved. Billing is paused
* **Snapshot** – A point-in-time capture of the filesystem state
* **Fork** – Create a new sandbox from the current state
* **Restore** – Bring the sandbox back to a previously saved state
* **Deleted** – Sandbox and all associated data are permanently removed and cannot be recovered

## Choosing a Template

Every sandbox starts from a template that defines the base operating system and pre-installed tooling available when the sandbox boots.

The available templates are documented in the Overview page. For most workloads, we recommend using `ubuntu-26.04-minimal`, which provides a general-purpose environment suitable for AI agents, code execution, and API integrations.

## Choosing Your Resources

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

Start with the defaults for your first sandbox. Resource configuration is fixed at creation time; if you need more resources later, create a new sandbox with the updated configuration.

## Install the SDK

NeevCloud provides official SDKs for both TypeScript and Python. Choose the SDK that best fits your application stack.

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

```bash
npm install @neevcloud/sdk
```

{% endtab %}

{% tab title="Python" %}

```bash
pip install neevai
```

{% endtab %}
{% endtabs %}

Supports Node.js 18+, Bun, Deno, and edge runtimes with global fetch (TypeScript/JavaScript). Python client supports Python 3.10+ with both synchronous (`NeevAI`) and asynchronous (`AsyncNeevAI`) clients.

For installation instructions, examples, and the complete Agent Service API documentation, see: Agent Service API | API Reference | neevcloud

## Set Your Credentials

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

```bash
export NEEV_API_KEY=your-api-key
export NEEV_ORG_ID=your-org-id
export NEEV_PROJECT_ID=your-project-id
```

{% endtab %}

{% tab title="Python" %}

```bash
export NEEVCLOUD_API_KEY=your-api-key
export NEEVCLOUD_ORG_ID=your-org-id
export NEEVCLOUD_PROJECT_ID=your-project-id
export NEEVCLOUD_REGION=as-south-1
```

{% endtab %}
{% endtabs %}

## Create Your First Sandbox

{% 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 %}

**Note:** Always call `waitUntilReady()` after creating a sandbox. It polls the sandbox phase until it transitions to Ready. Only then is it safe to run commands or perform file operations.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ai.neevcloud.com/agentic-studio/overview/getting-started.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.