Sandbox
Sandboxes: a short-lived Linux box to run code in.
with noclick.Sandbox.create(image="python", timeout_s=3600) as sb:
sb.files.write("/tmp/in.csv", csv_bytes)
print(sb.exec("python -c 'print(1 + 1)'").stdout)
build = sb.exec("make all", background=True, timeout_s=1800) # an Operation
print(build.wait().exit_code)
# terminated on exitclass SandboxA running sandbox. with noclick.Sandbox.create() as sb: terminates it on exit;
otherwise it stops at expires_at. Billed per second while it runs, at its
provider's price for the cpu and memory_mb it reserves.
- Like every live object, it also has hydrate(), refresh() and raw.
| id | string | |
| status | string | |
| image | string | null | |
| timeoutS | number | null | |
| cpu | number | null | |
| memoryMb | number | null | |
| region | RegionName | null | The region it runs in, or |
| userId | string | null | |
| expiresAt | Date | null | |
| createdAt | Date | null | |
| volumes | Record<string, string> | The volumes it mounts: |
| secretIds | string[] | The secrets in its environment, in order (a later one's key wins). |
| network | NetworkAccess | null | What it may reach: |
| files | SandboxFiles |
createstatic
static create(options?: SandboxCreateOptions): Promise<Sandbox>Start a sandbox (image "python" or "node") that lives
at most timeout_s seconds. network=True allows outbound
internet access, which is off by default. A list of up to 50 hosts allows
only those, over HTTPS on port 443: "pypi.org", or "*.example.com" for a
domain and its subdomains (a scheme, path, port or IP address raises
noclick.InvalidRequest).
region is where it runs (noclick.regions()): region=agent.region
puts it beside an agent. Without one it runs in your account's default
region, else wherever NoClick has capacity. Pinned to a region it costs what the
provider charges there: 1.15x in eu and ap, 1.75x in us-east and us-west.
volumes mounts Volumes (or their ids or names) read-write at
absolute paths, {"/data": vol}, up to 5: the sandbox sees each as it
was when it started, and what it writes there is saved every few seconds
while it runs, and all of it when it ends. A path can't be /,
/workspace itself or a system folder.
secrets (Secrets, ids or names; up to 20) become environment
variables for every command, a later secret's key winning a clash; the
sandbox keeps the values it started with. A volume's or secret's name is
the sandbox's user's own, else the account's (a user session's, its own only).
Lifetime before the sandbox is reclaimed.
Allow outbound internet access (off by default). A list of up to 50 hosts allows only those, over
HTTPS on port 443: "pypi.org", or "*.example.com" for a domain and its subdomains (a scheme,
path, port or IP address throws InvalidRequest).
Where it runs (regions()), for its whole life: region: agent.region puts it beside an
agent. Omitted, your account's default region, else wherever NoClick has capacity. Pinned to a
region it costs what the provider charges there: 1.15x in eu and ap, 1.75x in us-east and
us-west.
Volumes to mount read-write, by absolute path, up to 5: { "/data": Volume.fromName("datasets") }
(a Volume, an id or a name: the sandbox's user's own, else the account's). It sees each as it was
when it started; what it writes there is saved every few seconds while it runs, and all of it when
it ends. Not /, /workspace itself or a system folder.
Secrets whose keys become environment variables for every command (a Secret, an id or a name:
the sandbox's user's own, else the account's), up to 20; a later secret's key wins a clash, and
the sandbox keeps the values it started with.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
The sandbox, running and ready for commands. It stops on its own at expires_at.
fromIdstatic
static fromId(sandboxId: string, options?: CallOptions): SandboxA lazy reference to a sandbox by id, for one you started earlier.
A sandbox that loads the first time you read a field. Nothing is sent yet.
getstatic
static get(sandboxId: string, options?: CallOptions): Promise<Sandbox>Load a sandbox by id now; an unknown id raises noclick.NotFound.
The sandbox, loaded. Its status is starting, running, terminated or failed.
liststatic
static list(
options?: ReadOptions & { status?: SandboxStatusFilter; limit?: number },
): Promise<Sandbox[]>status: "live" lists the ones still starting or running.
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
Every matching sandbox, newest first, fetched page by page.
listPagestatic
static listPage(
options?: ReadOptions & PageOptions & { status?: SandboxStatusFilter },
): Promise<Page<Sandbox>>One page of sandboxes; pass nextCursor back as cursor.
The next_cursor of the page before; omit it for the first page.
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A page whose data holds the sandboxes and whose next_cursor is None on the last page.
exec
exec(
command: string,
options: ExecOptions & { background: true },
): Promise<Operation<ExecResult>>Run a bash command in /workspace; a non-zero exit is a normal result, not an error.
{ background: true } returns at once with an Operation whose wait() resolves to the
ExecResult: for commands longer than one request allows (timeoutS up to 3600, within the
sandbox's own lifetime).
Return at once with an Operation whose wait() resolves to the ExecResult.
Seconds before the command is stopped: 60 by default, at most 90, or 3600 with background.
What the command printed and how it exited: stdout and stderr (the last 64 KiB of each)
and exit_code. With background=True, an Operation at once, whose wait() gives that result.
terminate
terminate(): Promise<void>Stop the sandbox now (billing stops with it).
SandboxFiles
class SandboxFilesFiles inside a sandbox: await sandbox.files.write("a.py", "print(1)").
write
write(
path: string,
data: string | Uint8Array | ArrayBuffer | Blob,
): Promise<void>Write data (bytes, or text as UTF-8) to path, replacing it.
read
read(path: string): Promise<Uint8Array>Read the file at path; a missing file raises noclick.NotFound.
The file's bytes, exactly as stored; decode text yourself.
readTextTypeScript only
readText(path: string): Promise<string>ExecResult
interface ExecResultWhat a command printed and how it exited (a non-zero exit_code is a result, not an error).
| stdout | string | |
| stderr | string | |
| exitCode | number | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| ok | boolean | Whether the command exited 0. |