Custom images

Just use the Sailbox

Create a Sailbox and set it up the way you would any Linux machine: copy files in with sail box cp, run commands with sail box exec, or enable SSH and use scp and rsync. When it looks right, checkpoint it. Every Sailbox you start from that checkpoint boots with the same disk, and the same memory, already in place:

sail box checkpoint <id> --name after-setup
sail box from-checkpoint <checkpoint-id> --name worker-1

This is the fastest way to get many identical environments, and it needs no image at all. See Forking.

Use a container image you already have

Point Sailbox.create at an image on a public registry. Sail pulls it and layers what a Sailbox needs on top.

import sail

image = sail.Image.from_registry("myorg/my-custom-image:latest")
sb = sail.Sailbox.create(app=app, name="custom", image=image)

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

const image = Image.fromRegistry("myorg/my-custom-image:latest");
const sb = await Sailbox.create({ app, name: "custom", image });

use sail::imagebuild::ImageDefinition;

let image = ImageDefinition {
    oci_ref: Some("myorg/my-custom-image:latest".to_string()),
    ..Default::default()
};

Write the reference as you would for docker pull. The image must be Debian- or Ubuntu-based and publicly pullable from docker.io, ghcr.io, public.ecr.aws, or quay.io. Private registries are not supported.

How Sail treats your image

ENV, WORKDIR, and USER become the defaults for every command you run in the Sailbox. Commands run as the image’s USER when it sets one and as root otherwise. Pass user="0:0" on a call to run as root anyway.
ENTRYPOINT and CMD are not run. A Sailbox manages its own processes; your commands say what to execute.
The image keeps its own python3. Sail never installs another Python over it, because a pinned interpreter would shadow the one the image was built around.
A few paths are Sail’s. The build replaces /init and some Sail-owned files under /usr/local/bin, and writes configuration under /etc/sailbox and at /etc/profile.d/sailbox-env.sh. Everything else is left alone.
The Sailbox runs on the architecture the image was built for. An image published for both amd64 and arm64 runs on amd64; pass architecture to require one.

Build one from a Dockerfile

Already have a Dockerfile? Sail builds it for you.

image = sail.Image.from_dockerfile("./Dockerfile", context_dir=".")

const image = Image.fromDockerfile("./Dockerfile", { contextDir: "." });

use std::collections::HashMap;
use sail::imagebuild::{DockerfileInput, DockerfileSource, ImageDefinition};

let image = ImageDefinition {
    dockerfile: Some(DockerfileSource {
        dockerfile: DockerfileInput::Path("./Dockerfile".into()),
        context_dir: Some(".".into()),
        build_args: HashMap::new(),
        ignore: Vec::new(),
    }),
    ..Default::default()
};

context_dir is where COPY and ADD read from, with .dockerignore honored. Every FROM and COPY --from must name a public image on one of the registries above, and the result must be Debian- or Ubuntu-based. When a step fails, the error includes that step’s output.

Dockerfile support details

Pass a path or the Dockerfile text itself (contents= in Python, { contents } in TypeScript, DockerfileInput::Contents in Rust).
The build runs for amd64 unless you pass architecture. build_args fill ARG instructions like --build-arg. Names starting with BUILDKIT_ and Docker’s proxy variables (HTTP_PROXY and friends) are rejected; a RUN step can set a proxy for itself.
A Dockerfile.dockerignore next to the Dockerfile replaces the context’s .dockerignore, and ignore patterns you pass win over both. Python snapshots the context when you call from_dockerfile; TypeScript and Rust do it when the image is built. Edits after that point do not reach the build.
The context keeps file modes, empty directories, and symlinks. Hard links arrive as separate files. Setuid, setgid, and sticky bits, named pipes, device nodes, and mode 000 entries are rejected; sockets are skipped.
Up to 25 different images per Dockerfile across FROM and COPY --from.
Multi-stage builds, tmpfs mounts, and bind mounts from the context or another stage work. RUN --mount of type cache, secret, or ssh, a bind mount whose from names another image, mount options that are variable references, and ONBUILD (in your file or a base image) are rejected.
A # syntax= line may declare docker/dockerfile:1 or a release from 1.4 through 1.22.0. Anything else is rejected. The line does not change how the file is built.

Build one in code

No Dockerfile? Start from Sail’s Debian base and chain the steps you need. Each step returns a new definition, so one base can serve several variants.

image = (
    sail.Image.debian_amd64
    .apt_install("git", "curl")
    .pip_install("requests")
    .add_local_dir("./app", "/opt/app", ignore=["*.pyc", "__pycache__/"])
    .add_local_file("./config.json", "/etc/app/config.json", mode=0o600)
    .run_commands("python3 -m pip show requests >/tmp/requests.txt")
    .env({"APP_ENV": "production"})
)

const image = Image.debian("amd64")
  .aptInstall("git", "curl")
  .pipInstall("requests")
  .addLocalDir("./app", "/opt/app", { ignore: ["*.pyc", "__pycache__/"] })
  .addLocalFile("./config.json", "/etc/app/config.json", { mode: 0o600 })
  .runCommand("python3 -m pip show requests >/tmp/requests.txt")
  .env({ APP_ENV: "production" });

use std::collections::HashMap;

use sail::{BaseImage, ImageArchitecture};
use sail::imagebuild::{ImageDefinition, ImageDefinitionStep};

let image = ImageDefinition {
    base: Some(BaseImage::Debian),
    architecture: ImageArchitecture::Amd64,
    env: HashMap::from([("APP_ENV".to_string(), "production".to_string())]),
    steps: vec![
        ImageDefinitionStep::AptInstall(vec!["git".into(), "curl".into()]),
        ImageDefinitionStep::PipInstall(vec!["requests".into()]),
        ImageDefinitionStep::AddLocalDir {
            local_path: "./app".into(),
            remote_path: "/opt/app".into(),
            ignore: vec!["*.pyc".into(), "__pycache__/".into()],
            ignore_file: None,
        },
        ImageDefinitionStep::AddLocalFile {
            local_path: "./config.json".into(),
            remote_path: "/etc/app/config.json".into(),
            mode: Some(0o600),
        },
        ImageDefinitionStep::RunCommand(
            "python3 -m pip show requests >/tmp/requests.txt".to_string(),
        ),
    ],
    ..Default::default()
};

Step	What it does
`apt_install(...)`	Installs Debian packages.
`pip_install(...)`	Installs Python packages into the image’s `python3`.
`add_local_file(src, dst, mode=)`	Copies one file. `mode` sets its permissions.
`add_local_dir(src, dst, ignore=)`	Copies a directory tree, keeping file modes and skipping symlinks. `ignore` takes gitignore-style patterns or the path of a file like `.gitignore`.
`run_commands(...)`	Runs a shell command once, during the build.
`env({...})`	Sets environment variables for every command run from the image.

The same steps chain onto a registry image or a Dockerfile image too. Remote paths must be absolute and cannot contain a space, $, ", or \. Variable names must start with a letter or _ and contain only letters, digits, and _.

sail.Image.debian_amd64 and debian_arm64 also install a Python matching your local interpreter, so that @sail.function can run your Python functions inside the Sailbox. Use sail.Image.debian("amd64", install_python=False) to keep the base’s stock python3.

Building and caching

Pass an image definition to Sailbox.create and Sail uploads any local files, builds the image if it has not been built before, and starts the Sailbox from it. image_build_timeout (imageBuildTimeoutSeconds in TypeScript) bounds the build, retries included. In Rust the timeout is the duration passed to build_image_definition. To build ahead of time instead, call build on the definition and pass the result to Sailbox.create. In Rust, build_image_definition is the ahead-of-time build.

Builds are cached by content, per organization. The same base, steps, variables, and file contents reuse the existing image.
Tags are pinned, per organization. The first build from a tag such as python:3.13, or from a FROM line, pins the version the tag pointed at, and later builds keep it even after the tag moves upstream. Pass force_build (forceBuild in TypeScript, BuildMode::ForceBuild in Rust) to look the tag up again. That moves the pin for the whole organization; Sailboxes that already exist keep the version they started on. A digest (name@sha256:...) never moves.
The first build of a large image downloads all of it. Later builds usually reuse its layers.

Your image may boot when you are not looking

After a build, and periodically while an image is in use, Sail boots it outside any Sailbox to capture a start snapshot. Sailboxes created from the image resume from that snapshot instead of cold-booting, which keeps starts fast at every size.This makes two things part of the image contract:

Boot-time initialization runs during every hidden boot. systemd units and init scripts must be safe to run repeatedly, outside any Sailbox. Your entrypoint and the commands you run in a Sailbox never run during a hidden boot.
State written at boot is shared. Whatever boot leaves on disk or in memory is in the snapshot every Sailbox resumes from. Generate per-instance identity (machine IDs, nonces, cached credentials) at runtime, for example in your application’s entrypoint, not at boot. Environment variables, networking, and Sail-managed credentials are applied per Sailbox after the resume, so they behave the same either way.

Getting started

Inference

Sailboxes

Guides

Voyages

Security & compliance

Just use the Sailbox

Use a container image you already have

How Sail treats your image

Build one from a Dockerfile

Build one in code

Building and caching

​Just use the Sailbox

​Use a container image you already have

​How Sail treats your image

​Build one from a Dockerfile

​Build one in code

​Building and caching

Just use the Sailbox

Use a container image you already have

How Sail treats your image

Build one from a Dockerfile

Build one in code

Building and caching