example-coverage.md

Example coverage

Which runnable example shows which API, with a one-line snippet for each. For the examples themselves, see examples/README.md.

Contents

• API → examples
• Example catalog

API → examples (inverse index)

API / symbol	Example(s)	Example snippet
NeevAI(...)	tier-1, agent_patterns/*, workflow_examples/*, sandbox_lifecycle_controller.py	with NeevAI() as client:
AsyncNeevAI(...)	async_sandbox.py	async with AsyncNeevAI() as client:
client.sandboxes.create	tier-1, agent_patterns/*, workflow_examples/*, sandbox_lifecycle_controller.py, snapshot_fork_restore.py	sandbox = client.sandboxes.create({...})
client.sandboxes.create (restore)	snapshot_fork_restore.py	restored = client.sandboxes.create({..., "restore": snapshot_id})
client.sandboxes.create (lifecycle)	sandbox_lifecycle_windows.py	client.sandboxes.create({..., "lifecycle": {"idle_timeout_seconds": 60}})
client.sandboxes.create (BYOI image/command)	byoi_create.py	client.sandboxes.create({"image": "docker.io/library/python:3.12", "command": [...]})
client.sandboxes.create (labels)	sandbox_labels.py	client.sandboxes.create({...}, labels={"team": "payments"})
client.sandboxes.list	sandbox_lifecycle_controller.py	page = client.sandboxes.list(page=1, limit=20)
client.sandboxes.list (labels)	sandbox_labels.py	page = client.sandboxes.list(labels={"team": "payments"})
client.sandboxes.get	sandbox_lifecycle_controller.py	sandbox = client.sandboxes.get(sandbox_id)
client.sandboxes.update	sandbox_update.py	client.sandboxes.update(id, {"resources": {"cpu": 2}})
client.sandboxes.pause	sandbox_lifecycle_controller.py	sandbox = client.sandboxes.pause(sandbox_id)
client.sandboxes.resume	sandbox_lifecycle_controller.py	sandbox = client.sandboxes.resume(sandbox_id)
client.sandboxes.keepalive / sandbox.keepalive	sandbox_lifecycle_windows.py	sandbox.keepalive()
client.sandboxes.update_timeout / sandbox.update_timeout	sandbox_lifecycle_windows.py	sandbox.update_timeout({"idle_timeout_seconds": 300, "max_lifetime_seconds": 0})
client.sandboxes.delete	sandbox_lifecycle_controller.py	client.sandboxes.delete(sandbox_id)
client.sandboxes.metrics	sandbox_lifecycle_controller.py	metrics = client.sandboxes.metrics(sandbox_id)
client.sandboxes.audit / sandbox.audit	audit_trail.py	trail = sandbox.audit(limit=200) — calls, programs and connections
sandbox.execution_trace	—	sandbox.update({"execution_trace": False})
client.sandboxes.update (egress_add / egress_remove)	update_resize_egress.py	sandbox.update({"egress_add": {"allow": [{"host": "pypi.org"}]}})
sandbox.expose_port / .list_ports / .revoke_port / .get_url	preview_ports.py	url = sandbox.get_url(3000); sandbox.expose_port(3000, slug=new_slug) rotates it
sandbox.labels	sandbox_labels.py	sandbox.labels — {} when it has none
sandbox.addressable	—	sandbox.addressable — wait_until_ready() waits for it
client.sandboxes.create_snapshot	snapshot_fork_restore.py (via sandbox.snapshot)	pending = sandbox.snapshot({"name": "demo-snap"})
client.sandboxes.get_snapshot	snapshot_fork_restore.py	snap = client.sandboxes.get_snapshot(snapshot_id)
client.sandboxes.delete_snapshot	snapshot_fork_restore.py	client.sandboxes.delete_snapshot(snapshot_id)
sandbox.last_crash / agent.last_crash	last_crash.py	crash = sandbox.last_crash — None, or reason / at / storage_reset
sandbox.update	sandbox_update.py	sandbox.update({"resources": {"cpu": 2}}, allow_egress=["api.github.com"])
sandbox.snapshot	snapshot_fork_restore.py	pending = sandbox.snapshot({"name": "demo-snap"})
sandbox.fork	snapshot_fork_restore.py	fork = restored.fork("snapshot-fork")
client.templates.list	templates_list.py	page = client.templates.list(limit=10)
client.templates.get	templates_list.py	tpl = client.templates.get(template_id)
client.agents.create	create_agent.py	agent = client.agents.create({"name": "...", "agent_template": "claude-code"})
client.agents.list	—	page = client.agents.list(page=1, limit=20)
client.agents.get	—	agent = client.agents.get(agent_id)
client.agents.update	create_agent.py	agent = client.agents.update(agent.id, {"resources": {...}})
client.agents.pause / .resume	—	agent = client.agents.pause(agent_id) / client.agents.resume(agent_id)
client.agents.delete	create_agent.py	client.agents.delete(agent_id)
client.agents.keepalive / agent.keepalive	agent_ports_audit.py	agent.keepalive()
client.agents.rollback / agent.rollback	agent_snapshot_fork_rollback.py	agent.rollback(snapshot_id)
client.agents.create_snapshot / agent.snapshot	agent_snapshot_fork_rollback.py	snap = agent.snapshot({"name": "before-change"}, wait_until_ready=True)
client.agents.list_snapshots / agent.snapshots	agent_snapshot_fork_rollback.py	snaps = agent.snapshots()
client.agents.fork / agent.fork	agent_snapshot_fork_rollback.py	fork = agent.fork("web-fork"); fork.wait_until_ready()
agent.expose_port / .list_ports / .revoke_port / .get_url	agent_ports_audit.py	port = agent.expose_port(3000, slug=random_slug())
client.agents.audit / agent.audit	agent_ports_audit.py	trail = agent.audit(limit=20)
agent.idle_timeout_seconds	agent_ports_audit.py	print(agent.idle_timeout_seconds)
client.agent_templates.list	create_agent.py	page = client.agent_templates.list()
client.agent_templates.get	—	tpl = client.agent_templates.get(template_id)
agent.wait_until_ready	create_agent.py	agent.wait_until_ready(timeout_ms=120_000)
agent.refresh	agent_auto_resume.py	agent.refresh()
agent.sandbox	create_agent.py	sandbox = agent.sandbox()
agent.update	create_agent.py	agent.update({"resources": {"cpu": 2, "memory_gb": 4}})
agent.pause / agent.delete	create_agent.py	agent.pause(); agent.delete()
agent.resume	agent_auto_resume.py	agent.resume() — then wait_until_ready()
agent.to_json	—	agent.to_json()
client.raw.request	raw_request.py	data = client.raw.request("GET", path, query={...})
sandbox.wait_until_ready	tier-1 (except raw_request.py), processes.py, process_pool.py, agent_patterns/*, workflow_examples/*	sandbox.wait_until_ready(timeout_ms=120_000) — after connect_url is set in process examples
sandbox.refresh	processes.py, process_pool.py	sandbox.refresh() — poll until connect_url is set
sandbox.exec	parallel_fanout.py, async_sandbox.py, sandbox_metrics.py, agent_patterns/*, workflow_examples/*	result = sandbox.exec(["echo", "hi"]) / await sandbox.exec(...)
sandbox.exec_stream	streaming_exec.py, agent_patterns/minimal_agent.py, agent_patterns/utils/agent_loop.py	for event in sandbox.exec_stream(cmd):
sandbox.processes.start	processes.py, process_pool.py	proc = sandbox.processes.start(["sleep", "30"]) — after connect_url → Ready → runtime probe
sandbox.processes.follow	processes.py	for event in proc.follow():
sandbox.processes.logs	processes.py	page = proc.logs()
sandbox.processes.list	processes.py, process_pool.py	sandbox.processes.list() — runtime probe before start; list running processes after
sandbox.processes.kill	processes.py	proc.kill(signal=Signal.TERM)
SandboxTools / DESCRIPTIONS / PARAMETERS	agent_patterns/agent_tools_loop.py	tools = SandboxTools(sandbox, allow_processes=True)
SandboxTools.call	agent_patterns/agent_tools_loop.py	result = tools.call(name, args)
AsyncSandboxTools	—	result = await AsyncSandboxTools(sandbox).call(name, args)
sandbox.processes.get	—	sandbox.processes.get(proc.id) — no dedicated example; proc.wait() uses get(wait=True)
Process.status	—	proc.status() — no dedicated example
sandbox.processes.kill_all	process_pool.py	count = sandbox.processes.kill_all(signal=Signal.TERM)
Signal	processes.py, process_pool.py	proc.kill(signal=Signal.TERM)
Process.wait	processes.py, process_pool.py	final = proc.wait()
sandbox.files.write	files_api.py, snapshot_fork_restore.py, agent_patterns/utils/sandbox_tool.py, workflow_examples/repo_analyzer.py	sandbox.files.write("demo/message.txt", "original state")
sandbox.files.read	agent_patterns/utils/agent_loop.py	data = sandbox.files.read("path.txt")
sandbox.files.read_text	files_api.py, snapshot_fork_restore.py	text = sandbox.files.read_text("demo/message.txt")
sandbox.files.list	files_api.py	entries = sandbox.files.list("demo", recursive=True)
sandbox.files.upload_file	upload_download.py	sandbox.files.upload_file(source, "payload.bin", on_progress=show_progress)
sandbox.files.upload	—	sandbox.files.upload("big.bin", data, chunk_size=512 << 10) — write() uses it above 1 MiB
sandbox.files.download_file	upload_download.py	sandbox.files.download_file("payload.bin", copy) → {"bytes_written": n}
sandbox.metrics	sandbox_lifecycle.py, sandbox_metrics.py	metrics = sandbox.metrics()
sandbox.pause	sandbox_lifecycle.py, auto_resume.py	sandbox.pause()
sandbox.resume	auto_resume.py	sandbox.resume() — then wait_until_ready()
sandbox.delete	all examples that create sandboxes	sandbox.delete() / await sandbox.delete()
sandbox.to_json	sandbox_lifecycle_controller.py	sandbox.to_json()
sandbox.id / .phase / .connect_url	tier-1, processes.py, process_pool.py, sandbox_lifecycle_controller.py, agent_patterns/utils/sandbox_tool.py, workflow_examples/*	print(sandbox.phase, sandbox.connect_url) — polled until connect_url in process examples
client.close()	agent_patterns/utils/sandbox_tool.py	client.close()

Example catalog

Example	Path	Summary
Templates list & create	examples/templates_list.py	List templates, get by id, create sandbox, wait, delete
Agent lifecycle	examples/create_agent.py	List agent templates, create agent, wait, sandbox exec, update, pause, delete
Sandbox lifecycle	examples/sandbox_lifecycle.py	Create → wait → metrics → pause → delete
Auto-resume	examples/auto_resume.py	Create → pause → exec with no resume() → explicit resume() only on 429 while Paused → delete
Agent auto-resume	examples/agent_auto_resume.py	Create agent → pause → sandbox exec with no resume() → explicit agent.resume() only on 429 while Paused → delete
Sandbox in-place update	examples/sandbox_update.py	Create → wait → resize → re-scope egress → verify → delete
Sandbox labels	examples/sandbox_labels.py	Create two labelled sandboxes → list by one label → narrow by two → delete
Crash reporting	examples/last_crash.py	Create → mark file → force OOM → poll last_crash → check storage_reset → delete
Snapshot fork & restore	examples/snapshot_fork_restore.py	Write state → snapshot → modify → restore create → fork → cleanup
Async workflow	examples/async_sandbox.py	AsyncNeevAI create → wait → exec → delete
Files API	examples/files_api.py	Write, read_text, list (recursive)
Upload & download	examples/upload_download.py	Chunked upload_file with progress → download_file → compare sizes
Preview ports	examples/preview_ports.py	Serve a port → get_url → list_ports → rotate the slug → revoke_port
Resize & egress edits	examples/update_resize_egress.py	Resize + re-scope egress in one update → egress_add / egress_remove
Audit trail	examples/audit_trail.py	Run a script → read calls, programs and connections, each program tied to its call
Agent ports & audit	examples/agent_ports_audit.py	Agent preview port with slug → rotate → keepalive → audit → revoke
Agent snapshot, fork & rollback	examples/agent_snapshot_fork_rollback.py	Write state → snapshot → modify → fork → check fork has the modified file → rollback → check original state → cleanup
Streaming exec	examples/streaming_exec.py	exec_stream with progress output
Processes lifecycle	examples/processes.py	Create → connect_url wait → Ready → runtime probe → start → follow → logs → list → kill → wait
Process pool	examples/process_pool.py	Create → connect_url wait → Ready → runtime probe → parallel start → list → kill_all → wait
Parallel fan-out	examples/parallel_fanout.py	Multiple sandboxes, parallel exec
Sandbox metrics	examples/sandbox_metrics.py	Poll metrics() under CPU load
Raw request	examples/raw_request.py	Untyped client.raw.request
Lifecycle CLI	examples/sandbox_lifecycle_controller.py	CLI over client.sandboxes CRUD
Minimal agent	examples/agent_patterns/minimal_agent.py	Hand-rolled agent with exec_stream
Agent tools loop	examples/agent_patterns/agent_tools_loop.py	Function-calling loop on neevai.agent_tools: specs from DESCRIPTIONS + PARAMETERS, calls via tools.call
LangChain agent	examples/agent_patterns/langchain_agent.py	LangGraph ReAct via SandboxCodeExecutor
Sandbox tool helper	examples/agent_patterns/utils/sandbox_tool.py	SandboxCodeExecutor wrapper
Agent loop helper	examples/agent_patterns/utils/agent_loop.py	StreamingAgentLoop, exec_stream, files.read
Repo analyzer	examples/workflow_examples/repo_analyzer.py	Clone repo, agent audit, artifacts
Browser agent	examples/workflow_examples/browser_agent.py	Playwright scrape via agent loop