marimo
✓ verifiedsky/marimoReactive Python notebooks, with notebooks, Python and every package you install kept on the workspace volume.
- Runs
- 1 GPU (or CPU)
- Image
- buildpack-deps:noble-curl@sha256:6b03a2e5a50d3b482003a040045952cfbd7ed8081e1d6ac85f283b6e44fbff27
- Serves
- port 2718, ready at
/health(first start up to 15 min) - Licenses
- code: Apache-2.0
Clone
Versions
| # | Status | Notes | Contents | Sealed | Published | Clones |
|---|---|---|---|---|---|---|
| v1 | Published | First-party app definition | definition only | 2026-11-22 | 2026-11-22 | 0 |
README
marimo
marimo is a reactive Python notebook: notebooks are
plain .py files, and cells rerun when what they depend on changes.
Deployed as a workspace, everything lives on a skyfs volume in your
bucket and survives the VM:
- the notebooks;
- the Python interpreter and the environment, with every package the notebooks install;
~/.config/marimo, marimo's settings.
| Definition | sky-app.yaml, scripts/start.sh |
| Image | buildpack-deps:noble-curl, pinned by digest: Ubuntu 24.04 with curl and CA certificates (43 MB). No Python |
| Release | marimo 0.25.2 (MARIMO_VERSION) on CPython 3.12 (MARIMO_PYTHON), installed with uv 0.13.9 (UV_VERSION, checksum-pinned) |
| Port | 2718, readiness /health |
| GPUs | 1 by default; --app-gpus 0 runs on the CPU |
| First start | seconds after the image pull (about 7 s on a laptop): uv, CPython (92 MB), marimo's environment (200 MB) |
Deploy
From the console (/workspaces/new, app marimo), or:
skyws up nb --app marimo --cloud aws --gpus L40S:1 --region us-west-2
skyws open nb # http://127.0.0.1:2718, over SSH
skyws down nb # marimo exits, skyfs uploads the rest, the VM is terminated
marimo runs with --no-token: like every catalog app it is reached only
through the workspace's forward, never on the VM's public address.
Why nothing is in the image
The image is the OS and nothing else. uv, the interpreter, the venv and marimo are installed onto the volume at the first start, and found there on every start after, on any VM. Alternatives:
| Option | Verdict |
|---|---|
A Python image (python:3.12) with marimo in a venv on the volume |
Rejected: the venv points at the image's interpreter, so the environment is only valid with that exact image. With CPython on the volume, the environment and its interpreter travel together |
Bare ubuntu:24.04 |
Rejected: no curl and no CA certificates, so every start would apt-get install before it can fetch anything |
buildpack-deps:noble-curl: Ubuntu + curl + CA certificates; uv fetches a standalone CPython onto the volume |
Chosen |
What is kept, and where
| Path | What | Kept |
|---|---|---|
projects/<workspace>/ |
the notebooks; marimo serves this directory | yes |
envs/marimo-<version>-py<x.y.z>/ |
the venv: marimo, plus what notebooks install | yes |
apps/python/ |
CPython (a uv-managed standalone build) | yes |
apps/uv/<version>/ |
uv | yes |
home/ |
HOME: marimo's settings |
yes |
/cache/uv |
uv's download cache, on the VM | no |
How the template starts marimo
start.sh is idempotent; each step is skipped once done:
- uv. Downloads the pinned release for the VM's architecture, checks its sha256 and moves it in with one rename.
- CPython.
uv python install 3.12intoapps/python. uv's version pins which build that is. - Environment. A venv on that interpreter, with marimo. A marker file records completion. The venv is keyed by the marimo and Python versions, so changing either builds a new one beside the old.
- Serve.
marimo editon the project directory, on0.0.0.0:$APP_PORT.
Packages from notebooks. UV is set as uv run would set it, so
marimo's package manager is uv. It installs a notebook's missing packages
with uv pip install -p <the venv's python>, onto the volume, and they
are there on the next VM. GPU packages work the same way: PyTorch's wheels
bring their own CUDA runtime, and the driver comes from the node.
Verified
- AWS
g6e.xlarge(NVIDIA L40S) in us-west-2, created from the console's API as userryan:- serving 2 min 17 s after the request: the VM came up in 1.5 min, then the image pull and first start took 45 s;
- uv, CPython 3.12.16 and marimo's 25 packages installed onto the volume: 37 MB, 101 MB and 174 MB;
- the GPU is visible in the app container;
- marimo 0.25.2 served through the console's Open (the same forward as
skyws open).
- Locally, in Docker on arm64, with the volume as a Linux filesystem:
- first start healthy in 7 s;
- a fresh container on the same volume serving in 1 s, with every install skipped;
- marimo picked uv, and a package installed by its command landed in the venv on the volume.
- A case-insensitive filesystem (a macOS bind mount) cannot hold CPython's terminfo database. skyfs is case-sensitive.
Scripts
What runs in your workspace, from definition sha256:7ea77d808f23ac16272fca5e2cdc03627ad0fa0a2c4577de2e413868ca8d6714.
scripts/start.sh
#!/usr/bin/env bash
set -euo pipefail
# Everything but the OS lives on the volume: uv, CPython, the environment
# (marimo and whatever the notebooks install) and the notebooks. Caches
# stay on the VM.
project=$SKY_ROOT/projects/$SKY_WORKSPACE
tools=$SKY_ROOT/apps/uv/$UV_VERSION
export UV_PYTHON_INSTALL_DIR=$SKY_ROOT/apps/python
export UV_PYTHON_PREFERENCE=only-managed
# No `python3.12` shim in ~/.local/bin: the venv is the way in.
export UV_PYTHON_INSTALL_BIN=0
export UV_CACHE_DIR=/cache/uv
# The cache is on another filesystem: copy, never hard-link, into the venv.
export UV_LINK_MODE=copy
export UV_NO_PROGRESS=1
mkdir -p "$project" "$HOME" "$(dirname "$tools")" "$UV_PYTHON_INSTALL_DIR"
# 1. uv: the pinned release, checksum-verified, moved in with one rename.
if [ ! -x "$tools/uv" ]; then
case "$(uname -m)" in
x86_64) arch=x86_64 sum=$UV_SHA256_X86_64 ;;
aarch64) arch=aarch64 sum=$UV_SHA256_AARCH64 ;;
*) echo "marimo: unsupported architecture $(uname -m)" >&2; exit 1 ;;
esac
echo "marimo: installing uv $UV_VERSION"
rm -rf "$tools".partial.*
tmp=$tools.partial.$RANDOM
mkdir -p "$tmp"
tarball=$TMPDIR/uv.tar.gz
curl -fsSL --retry 3 -o "$tarball" \
"https://github.com/astral-sh/uv/releases/download/$UV_VERSION/uv-$arch-unknown-linux-gnu.tar.gz"
echo "$sum $tarball" | sha256sum -c --quiet -
tar -xzf "$tarball" -C "$tmp" --strip-components=1
mv "$tmp" "$tools"
fi
export PATH=$tools:$PATH
# 2. CPython, a standalone build managed by uv, on the volume.
uv python install "$MARIMO_PYTHON"
python=$(uv python find "$MARIMO_PYTHON")
pyver=$("$python" -c 'import sys; print("%d.%d.%d" % sys.version_info[:3])')
# 3. The environment: marimo, plus what notebooks install later (marimo's
# package manager uses uv into this same venv). A marker records
# completion; venvs hold absolute paths, so it is built in place.
env=$SKY_ROOT/envs/marimo-$MARIMO_VERSION-py$pyver
if [ ! -f "$env/.sky-complete" ]; then
echo "marimo: building $env"
rm -rf "$env"
uv venv --python "$python" "$env"
VIRTUAL_ENV=$env uv pip install "marimo==$MARIMO_VERSION"
touch "$env/.sky-complete"
fi
export VIRTUAL_ENV=$env PATH=$env/bin:$PATH
# marimo installs a notebook's missing packages with uv (set as `uv run`
# would), into this venv, so they are on the volume too.
export UV=$tools/uv
# 4. Serve the project directory. No token: like every catalog app it is
# reached only through the workspace's forward (skyws open), never
# exposed (docs/workspaces.md §6.4).
cd "$project"
exec marimo edit "$project" --host 0.0.0.0 --port "$APP_PORT" \
--headless --no-token --skip-update-check