createos-sandbox 0.1.0__tar.gz

createos_sandbox-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+  PYTHONUNBUFFERED: "1"
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install package and development tools
+        run: python -m pip install -e '.[dev]'
+      - name: Run tests
+        run: python -m pytest -q
+
+  quality:
+    name: Quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install package and development tools
+        run: python -m pip install -e '.[dev]'
+      - name: Check formatting
+        run: python -m ruff format --check src tests examples
+      - name: Lint
+        run: python -m ruff check src tests examples
+      - name: Type check
+        run: python -m mypy src/createos --ignore-missing-imports
+      - name: Check test coverage
+        run: >-
+          python -m pytest
+          --cov=createos
+          --cov-report=term-missing
+          --cov-fail-under=70
+
+  package:
+    name: Package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install build frontend
+        run: python -m pip install build
+      - name: Build source and wheel distributions
+        run: python -m build
+      - name: Install and import the built wheel
+        run: |
+          python -m pip install --force-reinstall dist/*.whl
+          python -c "import createos; print(createos.__version__)"

createos_sandbox-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+build/
+dist/
+*.egg-info/

createos_sandbox-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `createos-sandbox` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/).
+
+## Deprecation policy
+
+- Anything re-exported from `src/createos/__init__.py` is part of the public
+  API.
+- We are pre-1.0, so the API is allowed to break in MINOR bumps — breaking
+  changes ship as MINOR, and PATCH releases are bug-fix only.
+- Where possible, breaking changes are announced one minor before removal: the
+  old surface keeps working, gains a `DeprecationWarning`, and this file points
+  at the replacement.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-09-11
+
+Initial release.
+
+- `Client` with sandbox lifecycle (create, pause, resume, fork, destroy),
+  command execution and NDJSON streaming, file transfer and snapshots,
+  managed processes, networks, ingress previews, and custom templates.
+- Typed wire-contract models, typed errors, and `py.typed`.
+
+[Unreleased]: https://github.com/NodeOps-app/createos-python-sdk/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/NodeOps-app/createos-python-sdk/releases/tag/v0.1.0

createos_sandbox-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+
+Thank you for contributing to the CreateOS Python SDK.
+
+## Setup
+
+Create a virtual environment and install the SDK with its development tools:
+
+```sh
+python -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+```
+
+Run the complete local check suite:
+
+```sh
+.venv/bin/ruff format --check src tests examples
+.venv/bin/ruff check src tests examples
+.venv/bin/mypy src/createos --ignore-missing-imports
+.venv/bin/pytest --cov=createos --cov-fail-under=70
+```
+
+## Commit convention
+
+Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
+
+```text
+<type>(<optional-scope>): <subject>
+```
+
+Accepted types are `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`,
+and `perf`. Write the subject in imperative mood, keep it at 50 characters or
+fewer, start it with a lowercase letter, and do not end it with a period.
+
+Examples:
+
+```text
+feat(sandbox): add disk attachment
+fix(transport): honor retry-after header
+docs(readme): add network example
+test(processes): cover output replay
+chore: prepare v0.1.0 release
+```
+
+For an incompatible public API change, add `!` before the colon and explain the
+change in a `BREAKING CHANGE:` commit footer:
+
+```text
+feat(sandbox)!: change create response
+```
+
+## Before opening a pull request
+
+Run the complete local check suite. Add or update tests for behavior changes,
+and update public docstrings and README examples when the public API changes.
+
+## Releasing
+
+The package is published manually to PyPI as `createos-sandbox`.
+
+1. Bump `__version__` in `src/createos/_version.py` (the single source of
+   truth — `pyproject.toml` reads it) and move the `CHANGELOG.md`
+   `[Unreleased]` entries under the new version.
+2. Dry run the release gate: `./scripts/publish.sh --dry`.
+3. Publish: `./scripts/publish.sh`. It reruns tests, lint, types, builds the
+   sdist and wheel, uploads with `twine`, then tags and pushes `v<version>`.
+
+Uploading needs a PyPI API token, e.g. in `~/.pypirc` or as
+`TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-...`.

createos_sandbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NodeOps Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

createos_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,384 @@
+Metadata-Version: 2.5
+Name: createos-sandbox
+Version: 0.1.0
+Summary: Isolated sandboxes for AI agents and untrusted code: create, run commands, egress allowlist, pause/resume/fork, destroy. Python SDK for CreateOS Sandbox.
+Project-URL: Homepage, https://createos.sh
+Project-URL: Repository, https://github.com/NodeOps-app/createos-python-sdk
+Project-URL: Issues, https://github.com/NodeOps-app/createos-python-sdk/issues
+Project-URL: Changelog, https://github.com/NodeOps-app/createos-python-sdk/blob/main/CHANGELOG.md
+Author: NodeOps Inc.
+License: MIT
+License-File: LICENSE
+Keywords: agent,agents,ai,ai-agents,code-execution,compute,createos,createos-sandbox,e2b-alternative,egress,isolated-sandbox,isolation,runtime,sandbox,sdk,untrusted-code
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CreateOS Python SDK
+
+Launch an isolated cloud sandbox, run real commands, stream output, move files,
+open a preview URL, and tear everything down from Python.
+
+## Your first sandbox
+
+```sh
+pip install createos-sandbox
+```
+
+Python 3.10 or newer is required.
+
+```python
+from createos import Client, CreateSandboxRequest, RunCommandRequest
+
+
+with Client(api_key="your-api-key") as client:
+    sandbox = client.create_sandbox(
+        CreateSandboxRequest(
+            name="hello-python",
+            shape="s-4vcpu-4gb",
+            rootfs="devbox:1",
+        )
+    )
+    try:
+        response = sandbox.run_command(
+            RunCommandRequest(
+                command="sh",
+                arguments=[
+                    "-c",
+                    'printf "Python says hello from $(uname -m)\\n"',
+                ],
+            )
+        )
+        print(response.result.standard_output, end="")
+    finally:
+        sandbox.destroy()
+```
+
+```text
+Python says hello from x86_64
+```
+
+Do not commit a real API key to source control; inject it through your
+application's secret manager. You can configure the endpoint and default
+request timeout when constructing the client:
+
+```python
+client = Client(
+    api_key=api_key,
+    base_url="http://localhost:8080",
+    timeout=30,
+)
+```
+
+As an alternative, `Client()` reads `CREATEOS_SANDBOX_API_KEY` and
+`CREATEOS_SANDBOX_BASE_URL`. Explicit constructor arguments take precedence.
+
+## Documentation
+
+- [CreateOS Sandbox overview](https://nodeops.network/createos/docs/Sandbox/Overview)
+  explains the sandbox model, lifecycle, networking, storage, and isolation.
+- [CreateOS Sandbox documentation](https://nodeops.network/createos/docs)
+  contains the REST API reference and product guides.
+- [CreateOS Go SDK](https://github.com/NodeOps-app/createos-go-sdk) provides the
+  same sandbox capabilities for Go applications.
+- [CreateOS TypeScript SDK](https://github.com/NodeOps-app/createos-sandbox-sdk)
+  provides the same sandbox capabilities for JavaScript and TypeScript
+  applications.
+- [Runnable examples](#examples) demonstrate complete SDK workflows.
+- The public Python API is typed and documented with Python docstrings.
+- [Contributing guide](CONTRIBUTING.md) documents development checks and commit
+  conventions.
+
+## Stream output as it happens
+
+Long-running commands do not need to disappear behind a buffered HTTP call:
+
+```python
+import sys
+
+from createos import ExecStreamEventType, RunCommandRequest
+
+
+request = RunCommandRequest(
+    command="sh",
+    arguments=[
+        "-c",
+        'for n in 1 2 3; do echo "step $n"; sleep 1; done',
+    ],
+)
+
+with sandbox.stream_command(request) as stream:
+    for event in stream:
+        if event.type is ExecStreamEventType.STDOUT:
+            print(event.data, end="")
+        elif event.type is ExecStreamEventType.STDERR:
+            print(event.data, end="", file=sys.stderr)
+        elif event.type is ExecStreamEventType.EXIT:
+            print(f"exit code: {event.exit_code}")
+```
+
+Stopping early is safe: leaving the `with` block closes the response body and
+releases the underlying HTTP connection.
+
+## Move files without shell escaping
+
+```python
+sandbox.files.upload(
+    "/workspace/config.json",
+    b'{"mode":"production"}',
+)
+
+with sandbox.files.download("/workspace/config.json") as download:
+    contents = download.read()
+```
+
+`upload()` also accepts a binary file-like object, allowing large files to be
+transferred without reading them all into memory first.
+
+## Keep a process alive after disconnecting
+
+Managed processes are resources rather than fragile terminal sessions. Start
+one, reconnect from its output sequence, send input or signals, and wait for
+either the leader or its complete process tree:
+
+```python
+from createos import (
+    ManagedProcessCreateRequest,
+    ManagedProcessWaitOptions,
+    ManagedProcessWaitScope,
+)
+
+
+process = sandbox.processes.create(
+    ManagedProcessCreateRequest(
+        command="sh",
+        arguments=["-c", "sleep 1; echo managed process finished"],
+    )
+)
+
+finished = sandbox.processes.wait(
+    process.process_id,
+    ManagedProcessWaitOptions(
+        scope=ManagedProcessWaitScope.TREE,
+        wait_timeout=30,
+    ),
+)
+```
+
+## Turn a service into a URL
+
+Create a sandbox with ingress enabled, wait for the server to listen, then ask
+the instance for its public URL:
+
+```python
+from createos import CreateSandboxRequest, ManagedProcessCreateRequest
+
+
+sandbox = client.create_sandbox(
+    CreateSandboxRequest(
+        shape="s-4vcpu-4gb",
+        rootfs="devbox:1",
+        ingress_enabled=True,
+    )
+)
+
+sandbox.processes.create(
+    ManagedProcessCreateRequest(
+        command="python3",
+        arguments=[
+            "-m",
+            "http.server",
+            "8080",
+            "--bind",
+            "0.0.0.0",
+        ],
+    )
+)
+
+sandbox.wait_for_port(8080, host="127.0.0.1", timeout=15)
+print(sandbox.preview_url(8080))
+```
+
+## Everything is already connected
+
+Account-level services are initialized by `Client`:
+
+```python
+templates = client.templates
+networks = client.networks
+disks = client.disks
+
+custom_templates = templates.list()
+print(
+    f"{len(custom_templates)} templates ready; "
+    f"networks={type(networks).__name__} disks={type(disks).__name__}"
+)
+```
+
+Instance-level services are initialized when a sandbox handle is created or
+retrieved:
+
+```python
+sandbox.files
+sandbox.processes
+sandbox.computer.mouse
+sandbox.computer.keyboard
+sandbox.computer.windows
+sandbox.computer.screens
+```
+
+## Connect sandboxes on a private network
+
+Create an overlay network, attach a running sandbox, and inspect the resulting
+membership. Cleanup runs in reverse order, so the sandbox detaches before the
+network is deleted:
+
+```python
+from createos import NetworkCreateRequest
+
+
+network = client.networks.create(NetworkCreateRequest(name="agent-mesh"))
+try:
+    sandbox.attach_network(network.id)
+    try:
+        connected = client.networks.get(network.id)
+        for member in connected.members:
+            print(
+                f"sandbox={member.sandbox_id} "
+                f"private-ip={member.ip_address} "
+                f"status={member.status}"
+            )
+    finally:
+        sandbox.detach_network(network.id)
+finally:
+    client.networks.delete(network.id)
+```
+
+## Lifecycle reads like the domain
+
+```python
+sandbox.pause().wait_until_paused()
+
+clone = sandbox.fork()
+try:
+    sandbox.resume().wait_until_running()
+finally:
+    clone.destroy()
+
+sandbox.destroy()
+```
+
+The `SandboxInstance` handle safely caches the latest server projection.
+Lifecycle mutations and `refresh()` update it, while `id`, `name`, `status`,
+`ip_address`, and `data` provide safe reads.
+
+## Errors stay inspectable
+
+```python
+from createos import APIError, OperationTimeout
+
+
+try:
+    sandbox.wait_until_running()
+except APIError as error:
+    print(
+        f"HTTP {error.status_code}, code={error.code}, "
+        f"request={error.request_id}"
+    )
+except OperationTimeout:
+    # A lifecycle or readiness wait exhausted its budget.
+    pass
+```
+
+GET, HEAD, PUT, and DELETE requests are retried for transient network failures
+and retryable server responses. HTTP 429 and 503 are retried for every method.
+Configure the client with `RetryOptions`, or disable retries for one request
+with `RequestOptions(disable_retry=True)`.
+
+## Examples
+
+Runnable examples live under [`examples/`](examples/):
+
+- [Hello world](examples/hello_world/README.md)
+- [HTTP execution server](examples/execution_server/README.md)
+- [Command streaming](examples/command_streaming/README.md)
+- [Files and snapshots](examples/files_and_snapshots/README.md)
+- [Ingress preview](examples/ingress_preview/README.md)
+- [Private overlay network](examples/network/README.md)
+- [Custom template](examples/custom_template/README.md)
+- [Managed process lifecycle](examples/managed_process/README.md)
+- [Desktop and noVNC](examples/desktop/README.md)
+
+Together these examples cover command execution, file transfer, streaming,
+ingress, snapshots, networking, templates, managed processes, and desktop use.
+
+## Development
+
+Create a virtual environment and install the development dependencies:
+
+```sh
+python -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+```
+
+Run the same checks used while developing the SDK:
+
+```sh
+.venv/bin/ruff format --check src tests examples
+.venv/bin/ruff check src tests examples
+.venv/bin/mypy src/createos --ignore-missing-imports
+.venv/bin/pytest --cov=createos --cov-fail-under=70
+```
+
+The project follows the
+[Google Python Style Guide](https://google.github.io/styleguide/pyguide.html).
+Formatting, import ordering, public docstrings, and static analysis are enforced
+through the project configuration.
+
+GitHub Actions runs these quality checks, tests Python 3.10 through 3.14, builds
+both package distributions, and verifies that the generated wheel imports.
+
+Commits follow Conventional Commits. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for accepted types, examples, and the checks
+to run before opening a pull request.
+
+## Package layout
+
+```text
+src/createos/client.py      client configuration and account-level operations
+src/createos/instance.py    stateful sandbox lifecycle and command operations
+src/createos/services.py    files, processes, desktop, templates, disks, networks
+src/createos/models.py      public requests, responses, options, and enums
+src/createos/_transport.py  HTTP, authentication, retries, and JSend handling
+src/createos/_streams.py    NDJSON, SSE, command, process, and binary streams
+examples/                   runnable Python programs
+tests/                      mocked API contract tests
+```
+
+## About CreateOS
+
+[CreateOS](https://createos.sh) is an execution and governance platform for AI
+agents and applications. Learn more about isolated Firecracker-based workloads
+on the [CreateOS Sandbox product page](https://createos.sh/products/sandbox).
+
+## License
+
+This SDK is available under the [MIT License](LICENSE).