SDKs

Python SDK

sandscale 0.2.0. Every method and option, generated from the SDK source.

SDK overview · Errors · Regions

Client

Coming soon: the Python SDK is not on PyPI yet. This reference shows how it will work.

pip install sandscale

from sandscale import Sandscale
sandscale = Sandscale()  # reads SANDSCALE_API_KEY

Create one client and reuse it. Its methods are grouped by area below. Every call also takes a region.

sandscale.sandboxes

create

sandscale.sandboxes.create(*, template: Optional[str]=None, snapshot_id: Optional[str]=None, cpu_count: Optional[int]=None, memory_mb: Optional[int]=None, disk_mb: Optional[int]=None, timeout_seconds: Optional[int]=None, env: Optional[Mapping[str, str]]=None, vault_env: Optional[Sequence[Union[VaultEnvRef, Mapping[str, str]]]]=None, command: Optional[Sequence[str]]=None, name: Optional[str]=None, labels: Optional[Mapping[str, str]]=None, metadata: Optional[Mapping[str, str]]=None, region: Optional[str]=None) -> Sandbox

Starts a sandbox. Limits, entitlement and policy are decided by the server.

get

sandscale.sandboxes.get(sandbox_id: str, *, region: Optional[str]=None) -> Sandbox

list

sandscale.sandboxes.list(*, status: Optional[str]=None, project_id: Optional[str]=None, limit: Optional[int]=None, cursor: Optional[str]=None, region: Optional[str]=None) -> ListResult[Sandbox]

Lists sandboxes: of one region when one is named, else of every live region.

stop

sandscale.sandboxes.stop(sandbox_id: str, *, region: Optional[str]=None) -> None

Stops the sandbox and releases it.

pause

sandscale.sandboxes.pause(sandbox_id: str, *, region: Optional[str]=None) -> Raw

Pauses a microVM sandbox (409 pause_unsupported for a container sandbox).

resume

sandscale.sandboxes.resume(sandbox_id: str, *, region: Optional[str]=None) -> Raw

snapshot

sandscale.sandboxes.snapshot(sandbox_id: str, *, label: Optional[str]=None, region: Optional[str]=None) -> Snapshot

Snapshots the sandbox's /workspace; start from it with ``create(snapshot_id=...)``.

list_snapshots

sandscale.sandboxes.list_snapshots(sandbox_id: str, *, region: Optional[str]=None) -> List[Snapshot]

run

sandscale.sandboxes.run(sandbox_id: str, command: Union[str, Sequence[str]], *, env: Optional[Mapping[str, str]]=None, workdir: Optional[str]=None, timeout: int=60, stdin: Union[bytes, str, None]=None, on_stdout: Optional[Callback]=None, on_stderr: Optional[Callback]=None, region: Optional[str]=None) -> RunResult

Runs a command and returns its exit code and output.

logs

sandscale.sandboxes.logs(sandbox_id: str, run_id: str, *, from_chunk: Optional[int]=None, region: Optional[str]=None, on_done: Optional[Callable[[RunEnd], None]]=None) -> Iterator[OutputChunk]

Streams a run's output (Server-Sent Events), resuming after a dropped connection. ``on_done`` receives how the run ended, from the stream's done event.

write_file

sandscale.sandboxes.write_file(sandbox_id: str, path: str, data: Union[bytes, str], *, mode: Optional[str]=None, region: Optional[str]=None) -> None

read_file

sandscale.sandboxes.read_file(sandbox_id: str, path: str, *, region: Optional[str]=None) -> bytes

list_files

sandscale.sandboxes.list_files(sandbox_id: str, path: str, *, region: Optional[str]=None) -> List[FileEntry]

sandscale.workspaces

list

sandscale.workspaces.list(*, limit: Optional[int]=None, cursor: Optional[str]=None, all: bool=False, region: Optional[str]=None) -> ListResult[Workspace]

Lists workspaces: of one region when one is named, else of every live region.

get

sandscale.workspaces.get(workspace_id: str, *, region: Optional[str]=None) -> Workspace

start

sandscale.workspaces.start(workspace_id: str, *, region: Optional[str]=None) -> WorkspaceBuild

Queues a start build.

stop

sandscale.workspaces.stop(workspace_id: str, *, region: Optional[str]=None) -> WorkspaceBuild

Queues a stop build.

connect_info

sandscale.workspaces.connect_info(workspace_id: str, *, region: Optional[str]=None) -> ConnectInfo

SSH host and command, port forwarding and editor links, as the server allows.

sandscale.build_hosts

list_pools

sandscale.build_hosts.list_pools(*, region: Optional[str]=None) -> ListResult[Pool]

list

sandscale.build_hosts.list(*, scope: Optional[str]=None, state: Optional[str]=None, limit: Optional[int]=None, region: Optional[str]=None) -> ListResult[Lease]

The caller's leases (``scope="org"`` for every lease, where the server allows it).

get

sandscale.build_hosts.get(lease_id: str, *, region: Optional[str]=None) -> Lease

start

sandscale.build_hosts.start(pool_id: str, *, size: Optional[str]=None, ttl_seconds: Optional[int]=None, purpose: Optional[str]=None, repo: Optional[str]=None, region: Optional[str]=None) -> Lease

Takes a build host lease from a pool (it may wait for approval: ``pending_approval``).

stop

sandscale.build_hosts.stop(lease_id: str, *, region: Optional[str]=None) -> Lease

Releases the lease; the server wipes and deletes its host.

connect_info

sandscale.build_hosts.connect_info(lease_id: str, *, region: Optional[str]=None) -> LeaseConnectInfo

How to reach the lease's host: its workspace's connect info, or a lab host's SSH relay.

ssh_certificate

sandscale.build_hosts.ssh_certificate(lease_id: str, public_key: str, *, region: Optional[str]=None) -> SSHCertificate

A short-lived SSH certificate for the lease's host, for your public key.

Types

FileEntry

FieldTypeDescription
namestr
pathstr
is_dirbool
size optionalOptional[int]

LeaseConnectInfo

FieldTypeDescription
leaseLease
kindstr
workspace optionalOptional[ConnectInfo]
ssh_relay_path optionalOptional[str]
ssh_user optionalOptional[str]

ListResult

FieldTypeDescription
data optionallist[T]
pages optionallist[RegionPage]

OutputChunk

FieldTypeDescription
streamstr
datastr
chunk_indexint

RegionPage

One region's page of a list; lists without a region read every live region.

FieldTypeDescription
regionOptional[str]
has_more optionalbool
next_cursor optionalOptional[str]
error optionalOptional[SandscaleError]

RunResult

FieldTypeDescription
run_idstr
exit_codeint
stdoutstr
stderrstr
duration_ms optionalint
oom_killed optionalbool
timed_out optionalbool
streamed optionalbool

SSHCertificate

FieldTypeDescription
certificatestr
serialstr
key_idstr
principalslist[str]
sshRaw
valid_after optionalOptional[datetime]
valid_before optionalOptional[datetime]

VaultEnvRef

One Vault value of a sandbox's environment: variable ``name`` gets ``field`` of the secret at ``path``.

FieldTypeDescription
namestr
pathstr
fieldstr

This page is generated from the SDK source (sdk/python/sandscale). Do not edit it by hand.