Skip to main content
Sandbox is the synchronous handle for a running Nullspace sandbox. AsyncSandbox mirrors the same lifecycle and namespace methods with await.

​
Create And Connect

MethodUse
Sandbox.create(...)Launch from a template or reusable snapshot with sizing, timeout, metadata, envs, cwd, network, volumes, desktop config, and auto-resume options.
Sandbox.connect(id)Reconnect to a running sandbox or resume a paused alias and return a running handle.
Sandbox.list(...)Page through sandboxes with state, template, metadata, and field filters.
Sandbox.get_info_by_id(id)Read sandbox status without waking a paused sandbox.
Sandbox.run_once(command, args, ...)Create a sandbox, run one command, and clean up.
from nullspace import Sandbox

with Sandbox.create(template="base", timeout=300) as sandbox:
    print(sandbox.id)
    print(sandbox.commands.run("echo ready", shell=True).stdout)

​
Lifecycle

MethodUse
sandbox.kill()Destroy the sandbox and release runtime resources.
sandbox.pause() / sandbox.hibernate()Save paused state and stop the running VM.
Sandbox.resume(snapshot_id)Start a new running sandbox from a pause/resume snapshot.
sandbox.create_snapshot()Capture reusable baseline state while the source keeps running.
sandbox.fork()Branch the running sandbox into an independent child.
sandbox.set_timeout(...)Update timeout duration and timeout action.

​
Runtime Volumes

MethodUse
sandbox.list_volumes()List volume attachments for the running sandbox.
sandbox.attach_volume(volume, mount_path, read_only=False, subpath=None)Attach a volume ID, volume name, VolumeMount, or dictionary at runtime.
sandbox.detach_volume(attachment_id)Detach one runtime volume attachment.
sandbox.get_volume_health(attachment_id)Refresh and return runtime health for an attachment.
sandbox.remount_volume(attachment_id)Remount an attachment in place.

​
Namespaces

PropertyUse
sandbox.commandsForeground commands, streaming, background processes, stdin, logs, list, and kill.
sandbox.filesRead, write, upload, download, search, replace, and watch sandbox files.
sandbox.gitClone, branch, diff, commit, push, and configure Git inside the sandbox.
sandbox.ptyCreate and connect to interactive terminal sessions.
sandbox.desktopScreenshots, mouse/keyboard input, windows, clipboard, viewer streams, and recordings.
sandbox.code_interpreterStateful notebook-style code execution, contexts, package installs, runs, and artifacts.

​
Networking Helpers

MethodUse
sandbox.get_host_info(port)Return host mapping, signed HTTP URL, signed WebSocket URL, and expiration metadata.
sandbox.get_url(port)Return a signed browser HTTP URL for a sandbox port.
sandbox.get_websocket_url(port)Return a signed WebSocket URL for a sandbox port.
sandbox.get_preview_url(port)Return typed direct preview URL metadata, including HTTP and WebSocket signed URLs and grant metadata.
sandbox.create_signed_preview_url(port, ...)Create an explicit signed preview grant with optional expiry.
sandbox.list_preview_urls(port=...)List preview grants for a sandbox, optionally filtered by port.
sandbox.revoke_preview_url(grant_id)Revoke one preview grant and return revocation metadata.
sandbox.wait_for_preview(port, ...)Wait for route and service readiness before opening or sharing a preview link.
sandbox.create_preview_proxy_target(port, ...)Return marker-only upstream URLs plus header tokens for a customer-run preview proxy.
sandbox.create_ssh_access(public_key=..., expires_in_minutes=...)Mint short-lived OpenSSH certificate relay metadata for this sandbox.
sandbox.upload_url(path) / sandbox.download_url(path)Return signed file transfer URLs.
from nullspace import Sandbox, redact_preview_url

preview = sandbox.create_signed_preview_url(8080, expires_in_seconds=900)
readiness = sandbox.wait_for_preview(8080, timeout_secs=30)
print(readiness.ready)
print(redact_preview_url(preview.url))
SDK methods return raw URLs and header tokens so callers can open browsers or configure proxies intentionally. Use redact_preview_url(...) and redact_preview_token(...) before writing preview credentials to terminal logs, application logs, or support bundles. See Token model for the related credential families. 
from pathlib import Path

access = sandbox.create_ssh_access(
    public_key=Path("~/.ssh/id_ed25519.pub").expanduser().read_text(),
    expires_in_minutes=10,
)
print(access.command)