> 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/api-reference/ai-agent.md).

# Agent Service API

The Agent Service API manages **sandboxes** — isolated, on-demand compute environments for running AI agents and code on the NeevAI Supercloud. A sandbox provisions asynchronously (track its `phase`), can be paused to stop billable runtime while preserving its disks, and resumed later. Sandboxes are launched from **sandbox templates** that define the base environment.

The service also supports **snapshots**: point-in-time captures of a sandbox's filesystem state. From a snapshot you can restore a sandbox to an earlier state, fork it into a brand-new sandbox, or create fresh sandboxes from a saved baseline — useful for reproducible agent runs and fast environment cloning. (Capturing in-memory process state is coming soon.)

## SDKs

Prefer a typed client over raw HTTP? Official SDKs wrap this API with a `sandboxes` interface for sandbox lifecycle, plus file and command execution inside a sandbox.

### Node / TypeScript

[`@neevcloud/sdk`](https://www.npmjs.com/package/@neevcloud/sdk):

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

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

// apiKey, orgId, and projectId are required — pass them here or set the
// NEEV_API_KEY, NEEV_ORG_ID, and NEEV_PROJECT_ID environment variables.
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({ /* ... */ });
const result = await sandbox.exec(["sh", "-c", "echo hello"]);
// → { stdout, stderr, exitCode }
```

### Python

[`neevai`](https://pypi.org/project/neevai/) (Python 3.10+, sync `NeevAI` and async `AsyncNeevAI` clients):

```bash
pip install neevai
```

```python
from neevai import NeevAI

# Pass credentials here, or set NEEVCLOUD_API_KEY, NEEVCLOUD_ORG_ID,
# NEEVCLOUD_PROJECT_ID, and NEEVCLOUD_REGION in the environment.
with NeevAI(api_key="...", org_id="...", project_id="...", region="...") as client:
    sandbox = client.sandboxes.create({"name": "my-sandbox"})
    sandbox.wait_until_ready()
    result = sandbox.exec("echo hello")  # → stdout, stderr, exit_code
    client.sandboxes.delete(sandbox.id)
```

## What you can do

### Manage sandboxes

These operations are served by the REST endpoints documented in the interactive reference below.

* **Sandbox lifecycle** — list sandboxes in a project (paginated), create a sandbox, fetch one by ID, delete it, and pause/resume to control billable runtime without losing disks. (The SDKs add a wait-until-ready helper that polls the sandbox's `phase` until it is `Ready`.)
* **Health metrics** — read live health metric series for a sandbox over a configurable time window and resolution.
* **Snapshots** — capture a sandbox's filesystem state, list a sandbox's snapshots, fetch snapshot metadata (status and storage URI once ready), and delete a snapshot. Snapshots are asynchronous: they start `Pending` and must reach `Ready` before you restore or fork from them.
* **Restore & fork** — restore a sandbox in place from a chosen snapshot, or fork a sandbox's current live state into a brand-new sandbox (the source keeps running).
* **Sandbox templates** — browse the template catalogue and fetch a template by ID to use as the base environment when creating a sandbox.

### Work inside a sandbox

Once a sandbox is `Ready`, you connect directly to it (at its `connect_url`) to run code and manage files. These runtime operations are exposed through the SDKs (see above) rather than the gateway REST endpoints below.

* **Run commands** — execute a command inside the sandbox with `sandbox.exec`, either buffered (returning stdout, stderr, and the exit code) or streamed line-by-line, with optional working directory, environment variables, stdin, and timeout. A non-zero exit code is reported, not thrown.
* **Files** — read, write, and list files in the sandbox's workspace (raw bytes or UTF-8 text, including recursive directory listings). File access is binary-safe and workspace-relative.

Use the interactive reference below to inspect request payloads, the sandbox `phase` states, and response schemas, and to try each endpoint directly.


---

# 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/api-reference/ai-agent.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.