NeevAI Python SDK

Official Python client for the NeevCloud AI platform. Use it to provision sandboxes, run commands, manage files, and integrate with agent workflows.

Prerequisites

• Python ≥ 3.10
• Supported OS: Windows, macOS, Linux
• uv (recommended for running examples from this repo; optional if you use pip and a virtual environment)

See docs/getting-started.md for per-OS uv install commands and a full walkthrough.

Installation

pip install neevai

Install from source (contributors)

Clone the repository and install in editable mode with uv:

git clone https://github.com/NeevCloudAI/neev-sdk-python.git
cd neev-sdk-python
uv sync

uv sync creates a local environment and installs the package in editable mode. Run examples from the repo root with uv run python ....

Configure credentials

Set these environment variables before running scripts, or pass equivalent kwargs to NeevAI(...) / AsyncNeevAI(...).

Linux / macOS (bash/zsh) — current session:

export NEEV_API_KEY="your-api-key"
export NEEV_ORG_ID="org-abc123"
export NEEV_PROJECT_ID="proj-xyz789"

Windows PowerShell — current session:

$env:NEEV_API_KEY = "your-api-key"
$env:NEEV_ORG_ID = "org-abc123"
$env:NEEV_PROJECT_ID = "proj-xyz789"

Windows CMD — current session:

set NEEV_API_KEY=your-api-key
set NEEV_ORG_ID=org-abc123
set NEEV_PROJECT_ID=proj-xyz789

You can also pass credentials directly when creating the client:

from neevai import NeevAI

with NeevAI(api_key="...", org_id="...", project_id="...", region="...") as client:
    ...

Quick start (from clone)

If you just cloned the repo, follow these steps to reach your first successful run:

1. Clone and enter the repo (see Install from source (contributors) above if you have not already).

2. Install dependencies: uv sync.

3. Verify the install:

   uv run python -c "from neevai import NeevAI; print('ok')"
   

4. Run your first example:

   uv run python examples/templates_list.py
   

5. Expected outcome: the script lists available sandbox templates, fetches one by id, creates a sandbox from it, waits until it is ready, then deletes it.

6. Next: read docs/getting-started.md for full sync/async quick-start scripts and the documentation map.

Minimal code example

from neevai import NeevAI

with NeevAI(api_key="...", org_id="...", project_id="...", region="...") as client:
    sandbox = client.sandboxes.create({})
    sandbox.wait_until_ready()
    result = sandbox.exec("echo Hello World")
    print(result.stdout)
    client.sandboxes.delete(sandbox.id)

Detecting a crash

A sandbox that hits an OOM kill or another unexpected stop is restarted for you, so it reads back as Ready — but its filesystem may be gone. last_crash is how you tell:

crash = sandbox.last_crash  # None if this sandbox has never crashed
if crash and crash.storage_reset:
    # The sandbox restarted with an empty filesystem: files under /workspace,
    # and anything installed since create, are gone. Re-provision before using it.
    print(f"{crash.reason} at {crash.at}")

crash.storage_reset is False means it restarted with its files intact. The field records a past event and is not cleared when the sandbox recovers, so check crash.at before reacting to it. Agents expose the same agent.last_crash. See last_crash.py.

Network egress

Sandboxes (and agents) are deny-all by default — no outbound network. Open egress at create time with the convenience keyword args, on either sandboxes.create or agents.create:

# allow the whole internet
client.sandboxes.create({"name": "web", "sandbox_template_id": "..."}, allow_internet=True)

# allow only specific hosts (FQDN or CIDR; wildcards supported)
client.sandboxes.create({"name": "ci", "sandbox_template_id": "..."}, allow_egress=["github.com", "*.npmjs.org"])

# same on agents
client.agents.create({"name": "coder", "agent_template": "claude-code"}, allow_internet=True)

allow_internet=True opens 0.0.0.0/0 and ::/0. For finer control (ports, protocols, a mix of rules) pass a full egress object in params instead — it takes precedence over the convenience args.

Long-running processes

For detached workloads that outlive a single HTTP request, use sandbox.processes (unlike request-scoped sandbox.exec). Before processes.start, wait for connect_url (it may appear before phase == "Ready"), then sandbox.wait_until_ready(), then probe the sandbox runtime with sandbox.processes.list() (retry transient 502/503/504). Tune polling with NEEVAI_WAIT_TIMEOUT_MS and NEEVAI_POLL_INTERVAL_MS. See Processes API — end-to-end flow for auth, raw endpoints, and troubleshooting.

proc = sandbox.processes.start(["sh", "-c", "echo started; sleep 30"])
for event in proc.follow():
    if event["type"] == "stdout":
        print(event["data"], end="")
    elif event["type"] == "exit":
        print(f"exit {event['exit_code']}")
        break
final = proc.wait()

See examples/processes.py and examples/process_pool.py.

Agents

Provision a packaged agent from the catalogue template (agent_template is the template name, e.g. "claude-code"), wait for it to become Ready, then reach its environment through the backing sandbox:

from neevai import NeevAI

with NeevAI(api_key="...", org_id="...", project_id="...") as client:
    agent = client.agents.create({
        "name": "my-agent",
        "agent_template": "claude-code",
    })
    agent.wait_until_ready()
    sandbox = agent.sandbox()
    sandbox.files.write("notes.md", "# scratch\n")
    agent.update({"resources": {"cpu": 2, "memory_gb": 4}})
    agent.pause()
    agent.delete()

Browse templates with client.agent_templates.list() / .get(id). Region is optional on create — the client injects default_region only when set (unlike sandbox create, which requires a region). See examples/create_agent.py.

Examples

Runnable examples live under examples/. From the repo root, run any example with:

uv run python examples/<script>.py

See examples/README.md for the full catalogue and learning path.

Documentation

Start with docs/getting-started.md for installation, credentials, and your first sync/async script.

Contributors: update docs when the public API changes. See docs/development.md for the contributor workflow, typing notes, and test commands.

License

Apache 2.0