> 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/sandbox-runtime.md).

# Sandbox Runtime API

Operations that run *inside* a live sandbox: read and write files, run commands, manage long-running processes, and attach an interactive terminal. These are the runtime counterpart to the [Agent Service API](/api-reference/ai-agent.md), which creates and manages the sandboxes themselves.

Every request targets a single sandbox at its `connect_url` — the URL returned when you create the sandbox — and is authenticated with your project API key. Paths are always relative to the sandbox workspace root.

## SDKs

The official SDKs expose these operations through a `sandbox` handle, so you rarely call the endpoints directly. Create or fetch a sandbox with the Agent Service API, then work inside it.

### Node / TypeScript

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

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

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

const neev = new Neev({ apiKey: process.env.NEEV_API_KEY });
const sandbox = await neev.sandboxes.get("sandbox-id");

await sandbox.files.write("app.py", "print('hello')\n");
for await (const ev of sandbox.exec(["python", "app.py"], { stream: true })) {
  if (ev.type === "stdout") process.stdout.write(ev.data ?? "");
}
```

### Python

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

```bash
pip install neevai
```

```python
import os
from neevai import NeevAI

neev = NeevAI(api_key=os.environ["NEEV_API_KEY"])
sandbox = neev.sandboxes.get("sandbox-id")

sandbox.files.write("app.py", "print('hello')\n")
for ev in sandbox.exec_stream(["python", "app.py"]):
    if ev["type"] == "stdout":
        print(ev["data"], end="")
```

## What you can do

* **Files** — read, write, list, stat, check existence, make directories, remove, move, and watch for changes, all relative to the workspace root.
* **Commands** — run a command and stream its output line by line.
* **Processes** — start long-running processes, inspect them, follow their logs, and stop them.
* **Terminal** — attach an interactive terminal (PTY) over a WebSocket.

Use the interactive reference below to inspect request payloads and response schemas, with ready-to-copy TypeScript, Python, and cURL samples for each endpoint.


---

# 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/sandbox-runtime.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.