# Prime Sandboxes SDK
Lightweight Python SDK for managing Prime Intellect sandboxes - secure remote code execution environments.
## Features
- ✅ **Synchronous and async clients** - Use with sync or async/await code
- ✅ **Full sandbox lifecycle** - Create, list, execute commands, upload/download files, delete
- ✅ **Type-safe** - Full type hints and Pydantic models
- ✅ **Authentication caching** - Automatic token management
- ✅ **Bulk operations** - Create and manage multiple sandboxes efficiently
- ✅ **No CLI dependencies** - Pure SDK, ~50KB installed
## Installation
```bash
uv pip install prime-sandboxes
```
Or with pip:
```bash
pip install prime-sandboxes
```
## Quick Start
```python
from prime_sandboxes import APIClient, SandboxClient, CreateSandboxRequest
# Initialize
client = APIClient(api_key="your-api-key")
sandbox_client = SandboxClient(client)
# Create a sandbox
request = CreateSandboxRequest(
name="my-sandbox",
docker_image="python:3.11-slim",
cpu_cores=2,
memory_gb=4,
)
sandbox = sandbox_client.create(request)
print(f"Created: {sandbox.id}")
# Wait for it to be ready
sandbox_client.wait_for_creation(sandbox.id)
# Execute commands
result = sandbox_client.execute_command(sandbox.id, "python --version")
print(result.stdout)
# Clean up
sandbox_client.delete(sandbox.id)
```
## Async Usage
```python
import asyncio
from prime_sandboxes import AsyncSandboxClient, CreateSandboxRequest
async def main():
async with AsyncSandboxClient(api_key="your-api-key") as client:
# Create sandbox
sandbox = await client.create(CreateSandboxRequest(
name="async-sandbox",
docker_image="python:3.11-slim",
))
# Wait and execute
await client.wait_for_creation(sandbox.id)
result = await client.execute_command(sandbox.id, "echo 'Hello from async!'")
print(result.stdout)
# Clean up
await client.delete(sandbox.id)
asyncio.run(main())
```
## Authentication
The SDK looks for credentials in this order:
1. **Direct parameter**: `APIClient(api_key="sk-...")`
2. **Environment variable**: `export PRIME_API_KEY="sk-..."`
3. **Config file**: `~/.prime/config.json` (created by `prime login` CLI command)
## Advanced Features
### File Operations
```python
# Upload a file
sandbox_client.upload_file(
sandbox_id=sandbox.id,
file_path="/app/script.py",
local_file_path="./local_script.py"
)
# Download a file
sandbox_client.download_file(
sandbox_id=sandbox.id,
file_path="/app/output.txt",
local_file_path="./output.txt"
)
```
### Bulk Operations
```python
# Create multiple sandboxes
sandbox_ids = []
for i in range(5):
sandbox = sandbox_client.create(CreateSandboxRequest(
name=f"sandbox-{i}",
docker_image="python:3.11-slim",
))
sandbox_ids.append(sandbox.id)
# Wait for all to be ready
statuses = sandbox_client.bulk_wait_for_creation(sandbox_ids)
# Delete by IDs or labels
sandbox_client.bulk_delete(sandbox_ids=sandbox_ids)
# OR by labels
sandbox_client.bulk_delete(labels=["experiment-1"])
```
### Labels & Filtering
```python
# Create with labels
sandbox = sandbox_client.create(CreateSandboxRequest(
name="labeled-sandbox",
docker_image="python:3.11-slim",
labels=["experiment", "ml-training"],
))
# List with filters
sandboxes = sandbox_client.list(
status="RUNNING",
labels=["experiment"],
page=1,
per_page=50,
)
for s in sandboxes.sandboxes:
print(f"{s.name}: {s.status}")
```
## Documentation
Full API reference: https://github.com/PrimeIntellect-ai/prime-cli/tree/main/packages/prime-sandboxes
## Related Packages
- **`prime`** - Full CLI + SDK with pods, inference, and more (includes this package)
## License
MIT License - see LICENSE file for details
Raw data
{
"_id": null,
"home_page": null,
"name": "prime-sandboxes",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cloud, containers, remote-execution, sandboxes, sdk",
"author": null,
"author_email": "Prime Intellect <contact@primeintellect.ai>",
"download_url": "https://files.pythonhosted.org/packages/4d/bb/f7c8b0f3dd73651b456a6e2dbb6b7154c19aa7ed699b1faacd88dd82b9fa/prime_sandboxes-0.1.0.tar.gz",
"platform": null,
"description": "# Prime Sandboxes SDK\n\nLightweight Python SDK for managing Prime Intellect sandboxes - secure remote code execution environments.\n\n## Features\n\n- \u2705 **Synchronous and async clients** - Use with sync or async/await code\n- \u2705 **Full sandbox lifecycle** - Create, list, execute commands, upload/download files, delete\n- \u2705 **Type-safe** - Full type hints and Pydantic models\n- \u2705 **Authentication caching** - Automatic token management\n- \u2705 **Bulk operations** - Create and manage multiple sandboxes efficiently\n- \u2705 **No CLI dependencies** - Pure SDK, ~50KB installed\n\n## Installation\n\n```bash\nuv pip install prime-sandboxes\n```\n\nOr with pip:\n```bash\npip install prime-sandboxes\n```\n\n## Quick Start\n\n```python\nfrom prime_sandboxes import APIClient, SandboxClient, CreateSandboxRequest\n\n# Initialize\nclient = APIClient(api_key=\"your-api-key\")\nsandbox_client = SandboxClient(client)\n\n# Create a sandbox\nrequest = CreateSandboxRequest(\n name=\"my-sandbox\",\n docker_image=\"python:3.11-slim\",\n cpu_cores=2,\n memory_gb=4,\n)\n\nsandbox = sandbox_client.create(request)\nprint(f\"Created: {sandbox.id}\")\n\n# Wait for it to be ready\nsandbox_client.wait_for_creation(sandbox.id)\n\n# Execute commands\nresult = sandbox_client.execute_command(sandbox.id, \"python --version\")\nprint(result.stdout)\n\n# Clean up\nsandbox_client.delete(sandbox.id)\n```\n\n## Async Usage\n\n```python\nimport asyncio\nfrom prime_sandboxes import AsyncSandboxClient, CreateSandboxRequest\n\nasync def main():\n async with AsyncSandboxClient(api_key=\"your-api-key\") as client:\n # Create sandbox\n sandbox = await client.create(CreateSandboxRequest(\n name=\"async-sandbox\",\n docker_image=\"python:3.11-slim\",\n ))\n\n # Wait and execute\n await client.wait_for_creation(sandbox.id)\n result = await client.execute_command(sandbox.id, \"echo 'Hello from async!'\")\n print(result.stdout)\n\n # Clean up\n await client.delete(sandbox.id)\n\nasyncio.run(main())\n```\n\n## Authentication\n\nThe SDK looks for credentials in this order:\n\n1. **Direct parameter**: `APIClient(api_key=\"sk-...\")`\n2. **Environment variable**: `export PRIME_API_KEY=\"sk-...\"`\n3. **Config file**: `~/.prime/config.json` (created by `prime login` CLI command)\n\n## Advanced Features\n\n### File Operations\n\n```python\n# Upload a file\nsandbox_client.upload_file(\n sandbox_id=sandbox.id,\n file_path=\"/app/script.py\",\n local_file_path=\"./local_script.py\"\n)\n\n# Download a file\nsandbox_client.download_file(\n sandbox_id=sandbox.id,\n file_path=\"/app/output.txt\",\n local_file_path=\"./output.txt\"\n)\n```\n\n### Bulk Operations\n\n```python\n# Create multiple sandboxes\nsandbox_ids = []\nfor i in range(5):\n sandbox = sandbox_client.create(CreateSandboxRequest(\n name=f\"sandbox-{i}\",\n docker_image=\"python:3.11-slim\",\n ))\n sandbox_ids.append(sandbox.id)\n\n# Wait for all to be ready\nstatuses = sandbox_client.bulk_wait_for_creation(sandbox_ids)\n\n# Delete by IDs or labels\nsandbox_client.bulk_delete(sandbox_ids=sandbox_ids)\n# OR by labels\nsandbox_client.bulk_delete(labels=[\"experiment-1\"])\n```\n\n### Labels & Filtering\n\n```python\n# Create with labels\nsandbox = sandbox_client.create(CreateSandboxRequest(\n name=\"labeled-sandbox\",\n docker_image=\"python:3.11-slim\",\n labels=[\"experiment\", \"ml-training\"],\n))\n\n# List with filters\nsandboxes = sandbox_client.list(\n status=\"RUNNING\",\n labels=[\"experiment\"],\n page=1,\n per_page=50,\n)\n\nfor s in sandboxes.sandboxes:\n print(f\"{s.name}: {s.status}\")\n```\n\n## Documentation\n\nFull API reference: https://github.com/PrimeIntellect-ai/prime-cli/tree/main/packages/prime-sandboxes\n\n## Related Packages\n\n- **`prime`** - Full CLI + SDK with pods, inference, and more (includes this package)\n\n## License\n\nMIT License - see LICENSE file for details\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Prime Intellect Sandboxes SDK - Manage remote code execution environments",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/PrimeIntellect-ai/prime-cli/tree/main/packages/prime-sandboxes",
"Homepage": "https://github.com/PrimeIntellect-ai/prime-cli",
"Repository": "https://github.com/PrimeIntellect-ai/prime-cli.git"
},
"split_keywords": [
"cloud",
" containers",
" remote-execution",
" sandboxes",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e76bbfaa9d100a398c227e6af790452fd818f210a2f070e62391e7648da77009",
"md5": "aeca2adea84a06e36eade9dfb629959b",
"sha256": "67a408d2bc4f96d73f8266f01582ab402d566b96ad941f031d4c37bf95753767"
},
"downloads": -1,
"filename": "prime_sandboxes-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aeca2adea84a06e36eade9dfb629959b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14798,
"upload_time": "2025-10-09T01:06:49",
"upload_time_iso_8601": "2025-10-09T01:06:49.403261Z",
"url": "https://files.pythonhosted.org/packages/e7/6b/bfaa9d100a398c227e6af790452fd818f210a2f070e62391e7648da77009/prime_sandboxes-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4dbbf7c8b0f3dd73651b456a6e2dbb6b7154c19aa7ed699b1faacd88dd82b9fa",
"md5": "b397ba09cb97cdcf5d574304214b636e",
"sha256": "99d7c0a799aba8685a9583446886eb258a579be2b741066708a9afab6737212e"
},
"downloads": -1,
"filename": "prime_sandboxes-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b397ba09cb97cdcf5d574304214b636e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 34581,
"upload_time": "2025-10-09T01:06:50",
"upload_time_iso_8601": "2025-10-09T01:06:50.710283Z",
"url": "https://files.pythonhosted.org/packages/4d/bb/f7c8b0f3dd73651b456a6e2dbb6b7154c19aa7ed699b1faacd88dd82b9fa/prime_sandboxes-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-09 01:06:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PrimeIntellect-ai",
"github_project": "prime-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "prime-sandboxes"
}
JSON
