Skip to main content

AI-Q sandbox provider for Fly.io Sprites

aiq-sandbox-sprites runs NVIDIA AI-Q generated code in one isolated Fly.io Sprite per AI-Q job. It implements AI-Q's official third-party aiq.sandbox_providers entry point and LangChain Deep Agents' BaseSandbox contract.

This package is an alpha proof of concept. It deliberately reports resource limits as unsupported, so AI-Q fails closed if a workflow requests CPU or memory limits that Sprites cannot currently enforce through its public API.

Installation

Install AI-Q from NVIDIA's source distribution, then install the provider into that same Python environment:

pip install aiq-sandbox-sprites

AI-Q is installed from NVIDIA's source distribution. The provider declares the shared Deep Agents protocol rather than coupling its package metadata to the host application's distribution channel.

The provider requires AI-Q 2.2's aiq.sandbox_providers extension point. AI-Q 2.1 does not expose that interface and is not supported. The tested compatibility range covers AI-Q v2.2.1 with Deep Agents 0.6.8 and AI-Q revision bf4e67d1564ef8d2ec8f65b5f9001e512befc095 with Deep Agents 0.7.x. CI and release checks pin that revision.

Newer upstream versions renamed the Python namespace to deep_researcher_agent and the entry-point group to deep-researcher.sandbox_providers. Those versions are not supported by this release; use the compatible AI-Q revision above rather than the moving develop branch.

Set a restricted Sprites token on the AI-Q host:

export SPRITE_TOKEN="..."

The token is used by the host-side SDK. It is never copied into a Sprite or passed to generated code.

AI-Q configuration

Select sprites in the normal AI-Q sandbox block:

functions:
  deep_research_sandbox:
    _type: deep_research_sandbox
    provider: sprites
    workdir: /workspace
    network: blocked
    timeout: 1200
    idle_timeout: 1800
    artifact_capture:
      enabled: true
      max_file_bytes: 50000000
      allow_extensions: [.png, .jpg, .jpeg, .webp, .csv, .json, .md, .ipynb, .pdf]

AI-Q 2.2 does not yet expose third-party provider-specific fields in its YAML model. Configure the temporary Sprites-specific surface through environment variables:

Variable Default Purpose
SPRITE_TOKEN required Host-side Sprites API token
AIQ_SPRITES_API_URL https://api.sprites.dev Sprites API endpoint
AIQ_SPRITES_RUNTIME dev Sprite runtime; empty means the API default
AIQ_SPRITES_PYTHON_PACKAGES unset JSON array of locked package requirements installed before network policy
AIQ_SPRITES_MAX_OUTPUT_BYTES 1000000 Maximum combined command output returned to AI-Q
AIQ_SPRITES_MAX_DOWNLOAD_BYTES 50000000 Independent upper bound on one downloaded file
AIQ_SPRITES_VERIFY_NETWORK true Require live pre/post-policy connectivity probes
AIQ_SPRITES_NETWORK_VERIFY_TIMEOUT_SECONDS 10 Time allowed for policy enforcement
AIQ_SPRITES_DENY_PROBE_HOST 1.1.1.1 Known-reachable direct-IP egress probe
AIQ_SPRITES_DENY_PROBE_PORT 443 Probe TCP port

For the AI-Q analytics profile:

export AIQ_SPRITES_PYTHON_PACKAGES='["matplotlib", "numpy", "pandas", "pillow", "tabulate"]'

Lifecycle and security behavior

  • Job IDs are hashed into deterministic aiq-<digest> Sprite names and matching ownership labels.
  • Creation is attempted first. A name collision is attachable only when both the provider and exact job ownership labels match.
  • Trusted package bootstrap runs for a newly created Sprite, before generated code and before the final network restriction is installed.
  • An attached Sprite gets a check instead, because cleanup after a failed creation is best-effort: the ownership label proves the Sprite is ours, not that it finished bootstrap. Pinned packages already present are left alone, so a resumed sandbox is untouched. One that fails the check is installed into and, if that install fails, destroyed rather than handed to the job incomplete. Neither ordering guarantee above holds for an attached Sprite: it may already be network-restricted and may already have run generated code.
  • blocked maps to a wildcard deny policy; allowlist maps to explicit allow rules with default deny; open maps to an empty policy.
  • Restricted policies are checked through the policy API and a live direct-IP connectivity probe before the session is returned to AI-Q.
  • Command output is drained inside the Sprite while only a bounded head/tail is returned, preventing unbounded SDK buffers.
  • File downloads are streamed with a byte cap. Oversized files return the per-file file_too_large error instead of being loaded into host memory.
  • Close and terminate re-check the job ownership label before destroying the Sprite. Missing Sprites are treated as already cleaned up.

Provider cleanup cannot run if the complete AI-Q worker is lost. A production deployment still requires an external reaper scoped to the aiq-sandbox label and an authoritative job/expiry record.

Development

Tests use the current AI-Q sandbox source through PYTHONPATH and never create cloud resources:

PYTHONPATH=/path/to/aiq/src .venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/python -m build
.venv/bin/python -m twine check dist/*

The opt-in smoke test creates one disposable Sprite, runs commands and file transfer, verifies blocked egress, terminates the provider, and confirms the Sprite no longer exists:

AIQ_SOURCE_DIR=/path/to/aiq/src .venv/bin/python scripts/smoke_test.py

The broader live release matrix covers blocked, open, and allowlisted networking; binary transfer and size bounds; bounded output; command timeout recovery; package bootstrap; collision ownership; interrupted execution; and cleanup:

AIQ_SOURCE_DIR=/path/to/aiq/src \
AIQ_SPRITES_LIVE_TEST=1 \
.venv/bin/pytest -vv tests/test_live.py

After installing the built wheel into a complete AI-Q environment, exercise the real AI-Q runtime, artifact store, lifecycle events, and normal/interrupted cleanup:

python scripts/aiq_runtime_test.py

Metadata

Release files for aiq-sandbox-sprites 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiq-sandbox-sprites 0.1.1
File Size Uploaded Provenance Actions
aiq_sandbox_sprites-0.1.1.tar.gz 28.4 kB With provenance Details for aiq_sandbox_sprites-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiq-sandbox-sprites 0.1.1
File Interpreter ABI Platform Actions
aiq_sandbox_sprites-0.1.1-py3-none-any.whl Python 3 none any Details for aiq_sandbox_sprites-0.1.1-py3-none-any.whl

Total release size: 45.2 kB

Release files / aiq_sandbox_sprites-0.1.1.tar.gz

Download URL aiq_sandbox_sprites-0.1.1.tar.gz
Size 28.4 kB
Tags Source
SHA-256 checksum
How to use checksums
7bfecc1cb622b98a542c56da7023c9bff82f55a25870fc979d4ff37f48d99a68
BLAKE2b-256 checksum
How to use checksums
34fb21b88db1365588d88b27fc123fe7990440cbf6d44fa974df07db636919ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / aiq_sandbox_sprites-0.1.1-py3-none-any.whl

Download URL aiq_sandbox_sprites-0.1.1-py3-none-any.whl
Size 16.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
017186353d1091bff6e5145b479f4d0eab4b91e72bf8704260bf473abf7e5951
BLAKE2b-256 checksum
How to use checksums
398ed2080b90d388668dee302a3173f28a3ebf6a8ad501e26d7dcfa357457eea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Security for aiq-sandbox-sprites 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aiq_sandbox_sprites-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page