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.
blockedmaps to a wildcard deny policy;allowlistmaps to explicit allow rules with default deny;openmaps 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_largeerror 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.