Sailboxes

import sail

sb = sail.Sailbox.create(
    app=sail.App.find(name="example-app", mint_if_missing=True),
    name="sandbox-1",
)
print(sb.sailbox_id, sb.status)

import { App, Sailbox } from "@sailresearch/sdk";

const app = await App.find("example-app", { mintIfMissing: true });
const sb = await Sailbox.create({ app, name: "sandbox-1" });
console.log(sb.sailboxId, sb.status);

use sail::{Client, CreateSailboxRequest};

let client = Client::from_env()?;
let app = client.find_app("example-app", /* mint_if_missing */ true).await?;
let sb = client
    .create_sailbox(
        &CreateSailboxRequest {
            app_id: app.id,
            name: "sandbox-1".into(),
            ..Default::default()
        },
        /* timeout */ None,
    )
    .await?;
println!("{}", sb.sailbox_id());

import asyncio
import sail

async def main():
    app = await sail.App.find.aio(name="example-app", mint_if_missing=True)
    sb = await sail.Sailbox.create.aio(app=app, name="sandbox-1")
    proc = await sb.exec.aio("echo hi")
    result = await proc.wait()
    print(result.stdout)
    await sb.terminate.aio()

asyncio.run(main())

const sb = await Sailbox.create({ app, name: "sandbox-1" });
const proc = await sb.exec("echo hi");
const result = await proc.wait();
console.log(result.stdout);
await sb.terminate();

use sail::ExecOptions;

let sb = client.sailbox("sb_...");
let proc = sb.exec_shell("echo hi", ExecOptions::default()).await?;
let result = proc.wait().await?;
print!("{}", result.stdout);
sb.terminate().await?;

@classmethod
def create(
    *,
    app: App | str,
    image: ImageDefinition | None = None,
    name: str,
    image_build_timeout: int = 1800,
    timeout: int = 600,
    size: SailboxSize | None = None,
    memory_limit_gib: int | None = None,
    disk_limit_gib: int | None = None,
    ingress_ports: Sequence[int | IngressPort] | None = (),
    volumes: Mapping[str, Volume | str] | None = None,
    visibility: Literal["org", "private"] = "org",
    egress_policy: EgressPolicy | EgressPolicySummary | str | Mapping[str, Any] | None = None,
) -> Sailbox

static create(options: {
  app: App | string;
  name: string;
  image?: ImageSpec | Image; // defaults to a plain Debian base
  imageBuildTimeoutSeconds?: number; // 1800
  timeoutSeconds?: number; // 600 per create attempt; 0 = unbounded
  size?: "s" | "m" | "l";
  memoryLimitGib?: number;
  diskLimitGib?: number;
  ingressPorts?: (number | IngressPortInput)[];
  volumes?: Record<string, Volume | string>;
  visibility?: "org" | "private";
  egressPolicy?: EgressPolicy | EgressPolicySummary | string | EgressPolicyDocument;
}): Promise<Sailbox>

pub async fn create_sailbox(
    &self, // Client
    req: &CreateSailboxRequest,
    timeout: Option<Duration>,
) -> Result<Sailbox, SailError>

@classmethod
def get(sailbox_id: str) -> Sailbox

static get(sailboxId: string): Promise<Sailbox>

pub fn sailbox(&self, sailbox_id: impl Into<String>) -> Sailbox // Client

sb = sail.Sailbox.get("sb_...")
result = sb.exec("echo hello").wait()

const sb = await Sailbox.get("sb_...");
const result = await (await sb.exec("echo hello")).wait();

use sail::ExecOptions;

let sb = client.sailbox("sb_...");
let result = sb
    .exec_shell("echo hello", ExecOptions::default())
    .await?
    .wait()
    .await?;

@classmethod
def list(
    *,
    app_id: str | None = None,
    status: str | None = None,
    search: str | None = None,
    order: Literal["newest_active", "newest_created"] | None = None,
    limit: int | None = None,
) -> list[Sailbox]

static list(params?: {
  appId?: string;
  status?: SailboxStatusFilter;
  search?: string;
  order?: SailboxListOrder;
  limit?: number;
}): Promise<Sailbox[]>

pub async fn list_sailboxes(
    &self, // Client
    query: &ListSailboxesQuery,
) -> Result<SailboxPage, SailError>

@classmethod
def list_page(
    *,
    app_id: str | None = None,
    status: str | None = None,
    search: str | None = None,
    order: Literal["newest_active", "newest_created"] | None = None,
    limit: int = 50,
    offset: int = 0,
) -> SailboxPage

static listPage(query?: ListSailboxesQuery): Promise<SailboxPage>

pub async fn list_sailboxes(&self, query: &ListSailboxesQuery) -> Result<SailboxPage, SailError>

def exec(
    command: str | Sequence[str] | SailFunction,
    *function_args,
    timeout: int | None = None,
    background: bool = False,
    cwd: str | None = None,
    open_stdin: bool = False,
    pty: bool | PtyConfig = False,
    env: Mapping[str, str] | None = None,
    user: str | int | None = None,
    idempotency_key: str | None = None,
    output_mode: OutputMode | Literal["auto", "pipe", "tail"] = "auto",
    output_buffer_bytes: int = 1048576,
    kwargs: Mapping | None = None,
) -> ExecProcess | Any

exec(command: string | readonly string[], options?: {
  timeoutSeconds?: number;
  background?: boolean;
  cwd?: string;
  openStdin?: boolean;
  pty?: boolean | PtyConfig;
  env?: Record<string, string>;
  user?: string;
  idempotencyKey?: string;
  outputMode?: "auto" | "pipe" | "tail";
  outputBufferBytes?: number;
}): Promise<ExecProcess>

pub async fn exec_shell(&self, command: &str, options: ExecOptions)
    -> Result<ExecProcess, SailError>;
pub async fn exec(&self, argv: impl IntoIterator<Item = impl Into<String>>, options: ExecOptions)
    -> Result<ExecProcess, SailError>;

result = sb.exec("echo hi", timeout=5).wait()
print(result.stdout, result.exit_code)

# Stream output as it arrives (a chunk can be a partial line); the loop
# ends when the command finishes:
proc = sb.exec("for i in 1 2 3; do echo $i; sleep 1; done")
for chunk in proc.stdout:
    print(chunk, end="")

# Piping stdin:
proc = sb.exec("wc -l", open_stdin=True)
proc.stdin.write("one\ntwo\n")
proc.stdin.close()
print(proc.wait().stdout)

const result = await (await sb.exec("echo hi", { timeoutSeconds: 5 })).wait();
console.log(result.stdout, result.exitCode);

// Stream output as it arrives (a chunk can be a partial line); the loop
// ends when the command finishes:
const proc = await sb.exec("for i in 1 2 3; do echo $i; sleep 1; done");
for await (const chunk of proc.stdout) {
  process.stdout.write(chunk);
}

// Piping stdin:
const wc = await sb.exec(["wc", "-l"], { openStdin: true });
await wc.writeStdin("one\ntwo\n");
await wc.closeStdin();
console.log((await wc.wait()).stdout);

use sail::ExecOptions;
use std::time::Duration;

let result = sb
    .exec_shell(
        "echo hi",
        ExecOptions {
            timeout: Some(Duration::from_secs(5)),
            ..Default::default()
        },
    )
    .await?
    .wait()
    .await?;
print!("{} {}", result.stdout, result.exit_code);

// Piping stdin:
let wc = sb
    .exec(
        ["wc", "-l"],
        ExecOptions {
            open_stdin: true,
            ..Default::default()
        },
    )
    .await?;
wc.write_stdin(b"one\ntwo\n").await?;
wc.close_stdin().await?;
print!("{}", wc.wait().await?.stdout);

def run(
    command: str | Sequence[str],
    *,
    timeout: int | None = None,
    cwd: str | None = None,
    env: Mapping[str, str] | None = None,
    user: str | int | None = None,
    check: bool = False,
    idempotency_key: str | None = None,
    output_buffer_bytes: int = 1048576,
) -> ExecResult

run(command: string | readonly string[], options?: {
  timeoutSeconds?: number;
  cwd?: string;
  env?: Record<string, string>;
  user?: string;
  check?: boolean;
  idempotencyKey?: string;
  outputBufferBytes?: number;
  signal?: AbortSignal;
}): Promise<ExecResult>

pub async fn run(&self, argv: impl IntoIterator<Item = impl Into<String>>, options: RunOptions)
    -> Result<ExecResult, SailError>
pub async fn run_shell(&self, command: &str, options: RunOptions)
    -> Result<ExecResult, SailError>

result = sb.run("echo hello")
print(result.exit_code, result.stdout)

const result = await sb.run("echo hello");
console.log(result.exitCode, result.stdout);

use sail::RunOptions;

let result = sb.run_shell("echo hello", RunOptions::default()).await?;
println!("{} {}", result.exit_code, result.stdout);

def shell(
    command: str | None = None,
    *,
    shell: str | None = None,
    term: str | None = None,
    cwd: str | None = None,
    user: str | int | None = None,
    timeout: int | None = None,
    env: Mapping[str, str] | None = None,
    no_forward: bool = False,
) -> int

shell(command?: string, options?: {
  shell?: string;
  term?: string;
  cwd?: string;
  user?: string;
  timeoutSeconds?: number;
  env?: Record<string, string>;
  noForward?: boolean;
}): Promise<number>

pub async fn shell(
    &self,
    command: Option<&str>,
    options: ShellOptions,
) -> Result<i32, SailError>

sb.shell()

await sb.shell();

use sail::shell::ShellOptions;

sb.shell(/* command */ None, ShellOptions::default()).await?;

def read(path: str | PurePosixPath) -> bytes

read(path: string): Promise<Buffer>

pub async fn read(&self, path: &str) -> Result<Vec<u8>, SailError>

data = sb.fs.read("/workspace/output.txt")
print(data.decode())

const data = await sb.fs.read("/workspace/output.txt");
console.log(data.toString());

let data = sb.fs().read("/workspace/output.txt").await?;
println!("{}", String::from_utf8_lossy(&data));

def read_stream(path: str | PurePosixPath) -> FileStream  # iterable, sync and async

readStream(path: string): Promise<FileStream> // async-iterable

pub async fn read_stream(&self, path: &str) -> Result<FileReader, SailError>

with open("local.bin", "wb") as f:
    for chunk in sb.fs.read_stream("/workspace/large.bin"):
        f.write(chunk)

import { createWriteStream } from "node:fs";

const out = createWriteStream("local.bin");
for await (const chunk of await sb.fs.readStream("/workspace/large.bin")) {
  out.write(chunk);
}
out.end();

use std::io::Write;

let mut out = std::fs::File::create("local.bin")?;
let reader = sb.fs().read_stream("/workspace/large.bin").await?;
while let Some(chunk) = reader.next().await {
    out.write_all(&chunk?)?;
}

def write(
    path: str | PurePosixPath,
    data: str | bytes | bytearray | memoryview | IOBase,
    *,
    create_parents: bool = True,
    mode: int = 0o644,
    user: str | int | None = None,
) -> None

write(path: string, data: Buffer | Uint8Array | string, options?: {
  createParents?: boolean;
  mode?: number;
  user?: string;
}): Promise<void>

pub async fn write(
    &self,
    path: &str,
    data: &[u8],
    options: WriteOptions,
) -> Result<(), SailError>

sb.fs.write("/workspace/input.txt", "hello\n")

await sb.fs.write("/workspace/input.txt", "hello\n");

use sail::WriteOptions;

sb.fs()
    .write("/workspace/input.txt", b"hello\n", WriteOptions::default())
    .await?;

def write_files(
    files: Mapping[str | PurePosixPath, str | bytes | bytearray | memoryview | IOBase],
    *,
    create_parents: bool = True,
    mode: int = 0o644,
    user: str | int | None = None,
) -> None

writeFiles(files: Record<string, Buffer | Uint8Array | string>, options?: {
  createParents?: boolean;
  mode?: number;
  user?: string;
}): Promise<void>

pub async fn write_files<P: AsRef<str>, D: AsRef<[u8]>>(
    &self,
    files: impl IntoIterator<Item = (P, D)>,
    options: WriteOptions,
) -> Result<(), SailError>

sb.fs.write_files({"/workspace/a.txt": "first\n", "/workspace/b.txt": b"second\n"})

await sb.fs.writeFiles({
  "/workspace/a.txt": "first\n",
  "/workspace/b.txt": "second\n",
});

use sail::WriteOptions;

sb.fs()
    .write_files(
        [("/workspace/a.txt", &b"first\n"[..]), ("/workspace/b.txt", &b"second\n"[..])],
        WriteOptions::default(),
    )
    .await?;

def write_stream(
    path: str | PurePosixPath,
    *,
    create_parents: bool = True,
    mode: int = 0o644,
    user: str | int | None = None,
) -> FileWriter

writeStream(path: string, options?: {
  createParents?: boolean;
  mode?: number;
  user?: string;
}): Promise<FileWriter>

pub async fn write_stream(
    &self,
    path: &str,
    options: WriteOptions,
) -> Result<FileWriter, SailError>

with sb.fs.write_stream("/logs/run.log") as writer:
    for line in ["step 1 ok\n", "step 2 ok\n"]:
        writer.write(line)
# A clean exit finishes (commits); an exception aborts and propagates.

const writer = await sb.fs.writeStream("/logs/run.log");
try {
  for (const line of ["step 1 ok\n", "step 2 ok\n"]) {
    await writer.write(line);
  }
  await writer.finish();
} catch (err) {
  await writer.abort();
  throw err;
}

use sail::WriteOptions;

let mut writer = sb
    .fs()
    .write_stream("/logs/run.log", WriteOptions::default())
    .await?;
for line in ["step 1 ok\n", "step 2 ok\n"] {
    writer.write(line.as_bytes()).await?;
}
writer.finish().await?;
// Dropping an unfinished writer aborts the transfer.

def mkdir(path: str | PurePosixPath, *, user: str | int | None = None) -> None
def remove(path: str | PurePosixPath, *, user: str | int | None = None) -> None
def exists(path: str | PurePosixPath, *, user: str | int | None = None) -> bool

mkdir(path: string, options?: { user?: string }): Promise<void>
remove(path: string, options?: { user?: string }): Promise<void>
exists(path: string, options?: { user?: string }): Promise<boolean>

pub async fn mkdir(&self, path: &str, user: Option<&str>) -> Result<(), SailError>
pub async fn remove(&self, path: &str, user: Option<&str>) -> Result<(), SailError>
pub async fn exists(&self, path: &str, user: Option<&str>) -> Result<bool, SailError>

sb.fs.mkdir("/workspace/results")
if not sb.fs.exists("/workspace/results/run.lock"):
    sb.fs.remove("/workspace/results/stale")

await sb.fs.mkdir("/workspace/results");
if (!(await sb.fs.exists("/workspace/results/run.lock"))) {
  await sb.fs.remove("/workspace/results/stale");
}

sb.fs().mkdir("/workspace/results").await?;
if !sb.fs().exists("/workspace/results/run.lock").await? {
    sb.fs().remove("/workspace/results/stale").await?;
}

def ls(path: str | PurePosixPath, *, user: str | int | None = None) -> list[DirEntry]

ls(path: string, options?: { user?: string }): Promise<DirEntry[]>

pub async fn ls(&self, path: &str, user: Option<&str>) -> Result<Vec<DirEntry>, SailError>

for entry in sb.fs.ls("/workspace"):
    print(f"{entry.type:9} {entry.size:>8} {entry.name}")

for (const entry of await sb.fs.ls("/workspace")) {
  console.log(entry.type, entry.size, entry.name);
}

for entry in sb.fs().ls("/workspace").await? {
    println!("{:?} {} {}", entry.entry_type, entry.size, entry.name);
}

def upload_dir(local_dir: str | Path, guest_dir: str | PurePosixPath, *, user: str | int | None = None) -> None

uploadDir(dirs: { localDir: string; guestDir: string; user?: string }): Promise<void>

pub async fn upload_dir(&self, local_dir: &Path, guest_dir: &str, user: Option<&str>) -> Result<(), SailError>

sb.fs.upload_dir("./local_data", "/workspace/data")

await sb.fs.uploadDir({
  localDir: "./local_data",
  guestDir: "/workspace/data",
});

sb.fs().upload_dir(Path::new("./local_data"), "/workspace/data").await?;

def download_dir(guest_dir: str | PurePosixPath, local_dir: str | Path) -> None

downloadDir(dirs: { guestDir: string; localDir: string }): Promise<void>

pub async fn download_dir(&self, guest_dir: &str, local_dir: &Path) -> Result<(), SailError>

sb.fs.download_dir("/workspace/results", "./local_results")

await sb.fs.downloadDir({
  guestDir: "/workspace/results",
  localDir: "./local_results",
});

sb.fs().download_dir("/workspace/results", Path::new("./local_results")).await?;

def listener(guest_port: int) -> Listener
def listeners() -> list[Listener]
def wait_for_listener(
    guest_port: int,
    *,
    timeout: float = 60.0,
) -> Listener

listener(guestPort: number): Promise<Listener>
listeners(): Promise<Listener[]>
waitForListener(guestPort: number, options?: {
  timeoutSeconds?: number; // 60
  signal?: AbortSignal;
}): Promise<Listener>

pub async fn listener(&self, guest_port: u32) -> Result<Listener, SailError>;
pub async fn listeners(&self) -> Result<Vec<Listener>, SailError>;
pub async fn wait_for_listener(
    &self,
    guest_port: u32,
    options: WaitForListenerOptions, // timeout (60s)
) -> Result<Listener, SailError>;

listener = sb.wait_for_listener(3000, timeout=60)
print(listener.endpoint.url)

const listener = await sb.waitForListener(3000, { timeoutSeconds: 60 });
if (listener.endpoint?.kind === "http") {
  console.log(listener.endpoint.url);
}

use sail::{ListenerEndpoint, WaitForListenerOptions};

let listener = sb
    .wait_for_listener(3000, WaitForListenerOptions::default())
    .await?;
if let Some(ListenerEndpoint::Http { url }) = listener.endpoint() {
    println!("{url}");
}

def enable_ssh(
    *,
    allowlist: list[str] | None = None,
    wait: bool = True,
    timeout: float = 60.0,
) -> TcpEndpoint | None

enableSsh(options?: {
  allowlist?: string[];
  wait?: boolean; // true
  timeoutSeconds?: number; // 60
}): Promise<SshEndpoint | null>

pub async fn enable_ssh(
    &self,
    options: EnableSshOptions, // { allowlist, wait, timeout }
) -> Result<Option<SshEndpoint>, SailError>

def checkpoint(
    *,
    name: str | None = None,
    ttl_seconds: int | None = None,
) -> SailboxCheckpoint

checkpoint(options?: {
  name?: string;
  ttlSeconds?: number;
}): Promise<SailboxCheckpoint>

pub async fn checkpoint(
    &self,
    options: CheckpointOptions, // { name, ttl }
) -> Result<SailboxCheckpoint, SailError>

@classmethod
def from_checkpoint(
    checkpoint_id: str,
    *,
    name: str,
    timeout: int | None = None,
) -> Sailbox

static fromCheckpoint(options: {
  checkpointId: string;
  name: string;
  timeoutSeconds?: number;
}): Promise<Sailbox>

pub async fn create_from_checkpoint(
    &self, // Client
    checkpoint_id: &str,
    name: &str,
    timeout: Option<Duration>,
) -> Result<Sailbox, SailError>

def upgrade() -> UpgradeResult

upgrade(): Promise<UpgradeResult>

pub async fn upgrade(&self) -> Result<UpgradeResult, SailError>

def pause() -> None
def sleep(wake_at: Optional[datetime] = None) -> Optional[datetime]
def resume() -> Sailbox
def terminate() -> None

pause(): Promise<void>
sleep(wakeAt?: Date): Promise<Date | undefined>
resume(): Promise<void>
terminate(): Promise<void>

pub async fn pause(&self) -> Result<(), SailError>;
pub async fn sleep(&self, wake_at: Option<OffsetDateTime>) -> Result<Option<OffsetDateTime>, SailError>;
pub async fn resume(&self) -> Result<(), SailError>;
pub async fn terminate(&self) -> Result<(), SailError>;

import sail

vol = sail.Volume.find("shared-cache", mint_if_missing=True)

sb = sail.Sailbox.create(
    app=app,
    name="worker-1",
    volumes={"/mnt/cache": vol},
)

import { Sailbox, Volume } from "@sailresearch/sdk";

const vol = await Volume.find("shared-cache", { mintIfMissing: true });

const sb = await Sailbox.create({
  app,
  name: "worker-1",
  volumes: { "/mnt/cache": vol },
});

use sail::{CreateSailboxRequest, VolumeMount};

let vol = client.get_volume("shared-cache", /* mint_if_missing */ true).await?;

let sb = client
    .create_sailbox(
        &CreateSailboxRequest {
            app_id: app.id,
            name: "worker-1".into(),
            volume_mounts: vec![VolumeMount {
                volume_id: vol.volume_id,
                mount_path: "/mnt/cache".into(),
            }],
            ..Default::default()
        },
        /* timeout */ None,
    )
    .await?;

@staticmethod
def find(name: str, *, mint_if_missing: bool = False) -> Volume

@staticmethod
def list(*, max_objects: int | None = None) -> list[Volume]

def delete(*, allow_missing: bool = False) -> Volume | None

@staticmethod
def delete_by_name(name: str, *, allow_missing: bool = False) -> Volume | None

static find(
  name: string,
  options?: ClientOptions & { mintIfMissing?: boolean }
): Promise<Volume>
static list(options?: ClientOptions & { maxObjects?: number }): Promise<Volume[]>
delete(options?: { allowMissing?: boolean }): Promise<boolean>

pub async fn get_volume(&self, name: &str, mint_if_missing: bool) -> Result<VolumeInfo, SailError>
pub async fn list_volumes(&self, max_objects: Option<i64>) -> Result<Vec<VolumeInfo>, SailError>
pub async fn delete_volume(&self, volume_id: &str, allow_missing: bool) -> Result<Option<VolumeInfo>, SailError>

def set_egress_policy(policy: EgressPolicy | EgressPolicySummary | str | Mapping[str, Any]) -> SailboxEgressPolicy
def clear_egress_policy() -> SailboxEgressPolicy
egress_policy: SailboxEgressPolicy | None  # attribute; None on the handle create returns, set by get, set_egress_policy, and clear_egress_policy