Syva Docs

Documentation

Python SDK reference

Classes, methods, fields, and return types for syva.

Model

Name
Sandbox
Type
class
Description
Sandbox instance returned by create, get, and list.
Name
Image
Type
class
Description
Immutable image recipe used as a sandbox image input.
Name
sandbox.process
Type
SandboxProcessNamespace
Description
Foreground and background command namespace.
Name
sandbox.fs
Type
SandboxFilesystemNamespace
Description
Absolute-path filesystem namespace.

Create Sandboxes

Sandbox.create
operation
Sandbox.create(...) -> Sandbox
Creates a sandbox and waits for it to become ready or fail.
Name
image
default base
Type
str | Image
Description
Syva image reference, or an SDK image recipe that may start from a public registry image.
Name
cpu_cores
default 1
Type
int
Description
Virtual CPU cores.
Name
memory_mb
default 1024
Type
int
Description
Memory in MiB.
Name
ttl_seconds
Type
int
Description
Optional expiry window in seconds.
Name
network_policy
default allow-all
Type
"allow-all" | "deny-all"
Description
Outbound network policy.
Name
start_command
Type
str
Description
Command started when the sandbox boots.
Name
env
Type
dict[str, str]
Description
Default environment variables for commands.
Name
labels
Type
list[str] | dict[str, str]
Description
Labels stored with the sandbox.
Name
ports
Type
list[int | dict]
Description
Ports exposed through sandbox ingress.
Name
name
Type
str
Description
Unique-per-project handle for by-name lookup and resume.
Name
persistent
default True
Type
bool
Description
Snapshot the filesystem on stop so the sandbox can resume.
Name
snapshot_expiration_seconds
Type
int
Description
Snapshot TTL, reset on each use. 0 keeps snapshots until deleted.
Name
keep_last_snapshots
Type
int | dict
Description
Retention policy: count, or {count, expiration_seconds, delete_evicted}. Default keeps every snapshot.
Name
source_snapshot_id
Type
str
Description
Fork: create from a snapshot instead of an image.
Name
source_sandbox
Type
str
Description
Fork: create from another sandbox's latest snapshot, by id or name.
Returns Sandbox

Sandbox Object

Name
id
Type
str
Description
Sandbox id.
Name
state
Type
str
Description
Lifecycle state.
Name
image
Type
str
Description
Resolved image ref.
Name
resources
Type
dict[str, int]
Description
Allocated CPU, memory, and disk.
Name
network_policy
Type
str
Description
Outbound network policy.
Name
labels
Type
list[str]
Description
Labels attached at creation.
Name
ports
Type
list[dict]
Description
Declared port bindings and preview URLs.
Name
created_at
Type
str
Description
ISO timestamp.
Name
expires_at
Type
str | None
Description
ISO timestamp when an expiry was requested.
Name
error
Type
str | None
Description
Terminal error when present.
Name
name
Type
str | None
Description
Unique sandbox name when assigned.
Name
persistent
Type
bool
Description
Whether stop snapshots the filesystem.
Name
current_snapshot_id
Type
str | None
Description
Snapshot the next start resumes from.
Name
last_snapshot
Type
Snapshot | None
Description
Snapshot captured by the most recent stop().
Name
fs
Type
SandboxFilesystemNamespace
Description
Filesystem namespace.
Name
process
Type
SandboxProcessNamespace
Description
Command namespace.
Sandbox.configure(...)

Sets default base URL, API key, timeouts, and create retry settings.

Returns: None

Sandbox.create(...)

Creates a sandbox and waits for it to become ready or fail.

Returns: Sandbox

Sandbox.get(sandbox_id, ...)

Fetches an existing sandbox.

Returns: Sandbox

Sandbox.list(...)

Lists sandboxes for the API key.

Returns: list[Sandbox]

sandbox.refresh()

Reloads sandbox state.

Returns: Sandbox

Sandbox.get_by_name(name, ...)

Fetches a sandbox by its unique name.

Returns: Sandbox

Sandbox.get_or_create(name=..., ...)

Resumes the named sandbox, or creates it when missing.

Returns: Sandbox

sandbox.destroy()

Permanently deletes the sandbox, its snapshots, and frees its name.

Returns: Sandbox

sandbox.stop()

Stops the sandbox; persistent sandboxes snapshot their filesystem first.

Returns: Sandbox

sandbox.start()

Resumes a stopped persistent sandbox from its latest snapshot.

Returns: Sandbox

sandbox.snapshot(expiration_seconds=None)

Takes a manual snapshot; the sandbox stops.

Returns: Snapshot | None

sandbox.snapshots()

Lists this sandbox's live snapshots.

Returns: list[Snapshot]

sandbox.fork(name=None, persistent=True)

Creates a new sandbox from this sandbox's latest snapshot.

Returns: Sandbox

sandbox.update(...)

Updates persistence, expiration, retention, or rolls back via current_snapshot_id.

Returns: Sandbox

sandbox.kill()

Alias for destroy.

Returns: Sandbox

sandbox.extend_ttl(ttl_seconds=None, extend_seconds=None)

Sets or extends the expiry window.

Returns: Sandbox

sandbox.extend_timeout(duration_ms)

Extends the expiry window by milliseconds.

Returns: Sandbox

sandbox.wait(state="ready", timeout_ms=30000, poll_ms=100)

Polls until the sandbox reaches a lifecycle state.

Returns: Sandbox

sandbox.domain(port)

Returns the preview URL for an exposed port.

Returns: str

Snapshots

Persistent sandboxes snapshot their filesystem on stop() and resume with start(). See the Snapshots guide.

Name
id
Type
str
Description
Snapshot id.
Name
state
Type
str
Description
created, deleted, or failed.
Name
source
Type
str
Description
auto (taken on stop) or manual.
Name
sandbox_id
Type
str | None
Description
Owning sandbox.
Name
size_bytes
Type
int
Description
Stored (compressed) bytes; the billing basis.
Name
expires_at
Type
str | None
Description
Expiry, refreshed each time the snapshot is used.

Commands

sandbox.run_command
operation
sandbox.run_command(command, *, args=None, detached=False, ...) -> CommandFinished | Command
Runs foreground commands by default. Set detached=True to start a background command.
Name
args
Type
Iterable[str]
Description
Arguments passed after the command.
Name
cwd
Type
str
Description
Working directory inside the sandbox.
Name
timeout_ms
Type
int
Description
Command timeout in milliseconds.
Name
env
Type
dict[str, str]
Description
Environment variables for this command.
Name
detached
Type
bool
Description
Return a Command immediately instead of waiting for completion.
Returns CommandFinished | Command
sandbox.run_command(command, ...)

Runs a command. Set detached=True to return immediately.

Returns: CommandFinished | Command

sandbox.process.exec(command, ...)

Runs a foreground command.

Returns: CommandFinished

sandbox.process.start(command, ...)

Starts a background command.

Returns: Command

sandbox.process.get(process_id)

Fetches the latest command state.

Returns: Command

sandbox.process.output(process_id)

Returns stdout and stderr snapshot.

Returns: CommandOutput

sandbox.process.logs(process_id, stream="both")

Returns stdout, stderr, or combined log text.

Returns: str

sandbox.process.stream(process_id, ...)

Streams stdout, stderr, and final status events.

Returns: Iterator[CommandOutputEvent]

sandbox.process.stop(process_id)

Stops a running command.

Returns: Command

sandbox.process.wait(process_id, ...)

Waits for command completion.

Returns: Command

sandbox.process.list(limit=100)

Lists recent commands.

Returns: list[Command]

command.read_logs(stream="both")

Returns stdout, stderr, or combined log text.

Returns: str

sandbox.get_command(command_id)

Fetches a command through the sandbox helper.

Returns: Command

sandbox.list_commands(limit=100)

Lists commands through the sandbox helper.

Returns: list[Command]

CommandFinished

Name
exit_code
Type
int
Description
Process exit code.
Name
stdout
Type
str
Description
Captured stdout.
Name
stderr
Type
str
Description
Captured stderr.
Name
duration_ms
Type
int
Description
Runtime duration.
Name
timed_out
Type
bool
Description
True when the timeout killed the command.

Filesystem

Top-level helpers default to /workspace. sandbox.fs uses absolute paths.

sandbox.write_file(path, data, ...)

Writes under /workspace unless path is absolute.

Returns: None

sandbox.write_files(files, ...)

Writes multiple files under /workspace unless paths are absolute.

Returns: None

sandbox.read_file(path, ...)

Reads bytes, or None when missing.

Returns: bytes | None

sandbox.mkdir(path, ...)

Creates a directory under /workspace unless path is absolute.

Returns: FileInfo

sandbox.mk_dir(path, ...)

Alias for sandbox.mkdir().

Returns: FileInfo

sandbox.fs.write(path, data, ...)

Writes bytes or text to an absolute path.

Returns: None

sandbox.fs.write_file(path, data, ...)

Alias for sandbox.fs.write().

Returns: None

sandbox.fs.write_files(files, ...)

Writes multiple absolute-path files.

Returns: None

sandbox.fs.read(path)

Reads bytes from an absolute path.

Returns: bytes

sandbox.fs.read_file(path)

Alias for sandbox.fs.read().

Returns: bytes

sandbox.fs.stat(path)

Returns path metadata.

Returns: FileInfo

sandbox.fs.list(path)

Lists directory entries.

Returns: list[FileInfo]

sandbox.fs.find(path="/", ...)

Finds files and directories by type or pattern.

Returns: list[FileInfo]

sandbox.fs.grep(query, path="/", ...)

Searches file contents and returns matching lines.

Returns: list[GrepMatch]

sandbox.fs.mkdir(path, ...)

Creates a directory.

Returns: FileInfo

sandbox.fs.rm(path, ...)

Removes a file or directory.

Returns: None

Images

String images are Syva image refs. Public registry refs such as node:22 should be wrapped with Image.from_registry; Sandbox.create builds that recipe into a reusable Syva image before launch.

Image recipes are immutable. Every mutating method returns a new Image.

Image()

Creates a base image recipe from a Syva base ref.

Returns: Image

Image.from_registry(image, add_python=None)

Starts a recipe from a public Docker or OCI registry image.

Returns: Image

Image.syva_base()

Starts from the Syva base image.

Returns: Image

image.python(version="3.12")

Adds Python tooling.

Returns: Image

image.apt_install(packages)

Installs Debian packages.

Returns: Image

image.pip_install(packages, user=False)

Installs Python packages.

Returns: Image

image.npm_install(packages=None, global_=False)

Installs npm packages.

Returns: Image

image.run_cmd(commands, user=None)

Adds build-time shell commands.

Returns: Image

image.env(**values)

Adds default environment variables.

Returns: Image

image.workdir(path)

Sets the default workdir.

Returns: Image

image.user(user)

Sets the default user.

Returns: Image

image.copy(src, dest, ...)

Copies files into the build context.

Returns: Image

image.set_start_cmd(command, ready_command=None)

Sets boot and optional readiness commands.

Returns: Image

image.digest()

Returns a stable recipe digest.

Returns: str

Errors

Name
message
Type
str
Description
Human-readable error.
Name
code
Type
str | None
Description
Stable Syva error code.
Name
status
Type
int | None
Description
HTTP status when available.
Name
sandbox_id
Type
str | None
Description
Related sandbox id when available.
Name
retryable
Type
bool | None
Description
Whether retrying may succeed.