Guides / kosa8 Cloud / The universal image
The universal image
kosa8-universal is an Ubuntu 24.04 sandbox image with the tools most
builds and CI jobs reach for already installed, modelled on GitHub Actions'
ubuntu-latest runner, plus what an AI agent reaches for: the agent CLIs, MCP servers
already configured for them, every major cloud CLI, and data and AI libraries. Clone, build, test,
build a container and deploy, with nothing to install first. It is the image for the larger sandbox
sizes and for CI runner sandboxes. kosa8-universal-full adds the heavy toolchains and
full browsers.
Rolling out. The universal templates appear in the dashboard's template
list, and in GET /v1/templates, once a region has them. Until then, sandboxes use the
Alpine templates (base, python, node) described in
kosa8 Cloud.
Sizes
One template per size, all from the same image. Sandboxes this large start from the template's snapshot rather than a warm pool, so the first one in a region can take longer than a small sandbox.
| Template | vCPU | Memory |
|---|---|---|
universal-2x4 | 2 | 4 GiB |
universal-4x8 | 4 | 8 GiB |
universal-8x16 | 8 | 16 GiB |
universal-16x32 | 16 | 32 GiB |
curl -s -X POST https://api.kosa8.com/v1/sandboxes \
-H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
-d '{"template":"universal-4x8"}'
# then, in the sandbox: what is installed, and at which version
kosa8-image-check
What is in it
Every version is pinned, and every file the build downloads is checked against a published
checksum, so two builds of the same tag hold the same tools. Ubuntu's own packages come from a dated
snapshot of the archive (20261113T000000Z for the first tag).
kosa8-image-check prints them all and fails if any is missing;
/etc/kosa8-image.json lists them as JSON.
| Area | Tools and versions |
|---|---|
| Base | Ubuntu 24.04 LTS (pinned by digest), C.UTF-8, UTC |
| Source control | git 2.56.1 (git-core PPA), git-lfs 3.8.1, gh 2.104.0, openssh-client |
| C and C++ | build-essential (gcc and g++ 13, make), clang and lld 18, cmake 3.28, ninja, pkg-config, autoconf, automake, libtool |
| Node.js | Node 22.23.5 (default) and 24.22.3 through mise 2026.11.8; npm, pnpm 12.18.0 and yarn 1.22.22 (corepack), bun 1.4.4 |
| Python | Python 3.12 with pip and venv, uv 0.13.8, pipx |
| Go | Go 1.27.4 |
| Rust | Rust 1.100.0 through rustup 1.29.3 (minimal profile, plus rustfmt and clippy) |
| Java | Eclipse Temurin 21.0.13+9, Maven 3.9.16, Gradle 9.9.1 |
| Ruby and PHP | Ruby 3.2 with gem and bundler 2.4.22; PHP 8.3 CLI with xml, dom, mbstring, curl and zip; Composer 2.11.2 |
| Containers | Docker 29.9.3 CLI, buildx 0.39.0, compose 5.7.1; dockerd, containerd and runc |
| Agent CLIs | Claude Code 2.1.325, OpenAI Codex 0.169.0, Gemini CLI 0.68.0, GitHub Copilot CLI 1.0.112, opencode 1.19.5, goose 1.59.1, aider 0.86.2. No API key is in the image: each agent uses your own key or sign-in. Amp and Cursor's agent are one command away (kosa8-install amp, kosa8-install cursor-agent), as their terms do not allow shipping them |
| MCP servers | Configured for every agent above (see MCP servers): filesystem, git, fetch, memory, sequential-thinking, time, Playwright (headless Chromium) and kosa8 Cloud; installed and one command away: GitHub, Terraform, Kubernetes, Azure, gcloud, AWS docs, Postgres (MCP Toolbox), MongoDB, Sentry, Notion, Brave Search, and hosted Cloudflare, Stripe, Supabase, Neon, Linear, Hugging Face |
| Cloud and deploy | kubectl 1.37.2, helm 4.3.2, kustomize 5.8.3, terraform 1.17.2, ansible-core 2.21.6; AWS CLI 2.40.3, gcloud 593.0.0 (gsutil, bq), Azure CLI 2.92.0, vercel 65.16.0, wrangler 4.162.0, railway 5.74.0; glab 1.130.0, stripe 1.55.11, sentry-cli 3.8.2, cloudflared 2026.11.0. netlify, firebase, heroku, doctl, flyctl, supabase, OpenTofu, Pulumi and k9s are in kosa8-universal-full |
| More languages | Deno 2.9.8, TypeScript 7.0.2, tsx; poetry, conan, pre-commit, mypy; meson; Lua 5.4 and luarocks; Perl with cpanminus |
| Test, lint, security | Playwright 1.65.1 with headless Chromium, jest, vitest, pytest; eslint, prettier, biome, ruff, golangci-lint, hadolint, actionlint, shellcheck; gitleaks. The semgrep, trivy, grype, syft and cosign scanners are in kosa8-universal-full |
| Data and AI | The default Python environment (/opt/python): numpy, pandas, polars, pyarrow, duckdb, matplotlib, JupyterLab, pytest, and the anthropic, openai, google-genai, mistralai, huggingface_hub (hf), ollama and mcp SDKs. The same SDKs for Node, on NODE_PATH. duckdb 1.5.6 |
| Databases | sqlite3, psql (PostgreSQL 16 client), mysql (8.0 client), redis-cli, duckdb (mongosh is in kosa8-universal-full) |
| Everyday tools | curl, wget, httpie, jq, yq 4.54.3, ripgrep, fd, fzf, bat, tmux, vim, neovim 0.12.6, nano, zip, unzip, 7zip, xz, zstd, pigz, rsync, shellcheck, parallel, tree, htop, lsof, strace, socat, file, less, sudo, ping, dig, nc; ffmpeg, ImageMagick, pandoc, graphviz, poppler-utils, tesseract |
Apt package versions (gcc, clang, cmake, Ruby, PHP, Python) are the snapshot's; the exact ones
are in the image's SBOM. apt-get update in a sandbox reads today's Ubuntu archive, not
the snapshot, so apt-get install works as usual.
Other versions
mise manages Node, so a project's mise.toml, .nvmrc or
.node-version picks its own: mise use node@24 switches without a download,
since 24 is already installed. Other versions are a command away:
mise use node@20 # any Node; also ruby@3.4, php@8.4, java@17 … uv python install 3.13 # another Python, beside 3.12 rustup toolchain install nightly corepack use pnpm@9 # a project's own package manager version
Users and paths
| Item | Details |
|---|---|
| Commands run as | root, in /workspace (the sandbox's disk, kept while it sleeps) |
runner | uid 1001 with passwordless sudo, in the docker group, as on GitHub's runners. Use sudo -iu runner for a tool that refuses root. |
| Tool homes | /opt/mise, /opt/rust (RUSTUP_HOME, CARGO_HOME), /opt/java/temurin-21 (JAVA_HOME), /usr/local/go; shared by both users |
| Python packages | python3 and pip are the default environment /opt/python (a virtual environment of Ubuntu's 3.12, owned by runner), so pip install works as is. A project's own uv venv or python3 -m venv works as usual; Ubuntu's own Python is /usr/bin/python3. Python CLIs (az, aider, ansible, poetry …) each have their own environment under /opt/pytools. |
| npm CLIs | Each in its own directory under /opt/npm-tools, linked into /usr/local/bin. Claude Code's auto-update is off (DISABLE_AUTOUPDATER=1), so the image version stays put; npm i -g installs a newer one beside it. |
MCP servers
The agents (Claude Code, Codex, Gemini CLI, opencode, Copilot CLI and Cursor) find the default
MCP servers in their own config files for root and runner, so an agent
started in a sandbox has them with no setup. kosa8-mcp manages them:
kosa8-mcp list # every server, on or off, and what it needs kosa8-mcp add github # turn one on for every agent (reads GITHUB_PERSONAL_ACCESS_TOKEN) kosa8-mcp remove playwright kosa8-mcp test filesystem # start a server and list its tools
No secret is stored in the image. A server that needs a token reads it from the environment when
the agent starts it, and a hosted server is sent Authorization: Bearer $VAR. The kosa8
Cloud server needs KOSA8_API_KEY; without it the agent shows that one server as
failing to connect.
Docker inside a sandbox
The Docker CLI, buildx and compose are installed, and so are dockerd,
containerd and runc. To run the daemon, create the sandbox with
"docker": true and a size. It is then persistent, since the daemon has to outlive the
command that starts it:
curl -s -X POST https://api.kosa8.com/v1/sandboxes \
-H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
-d '{"size":"4x8","image":"kosa8-template/universal-24.04-20261114.1","docker":true}'
# then, in the sandbox
dockerd > /var/log/dockerd.log 2>&1 &
docker run --rm hello-world
Images are pulled over the sandbox's own network, so its egress policy applies to them. They are
kept on the sandbox's disk in /var/lib/docker.
What it grants. The sandbox's container gets the privileges the daemon needs: its own
cgroup tree, every capability and no seccomp filter. Those hold only inside the sandbox's own
microVM, which stays the isolation boundary: egress rules and secrets are enforced on the host,
outside the VM, and no other sandbox shares the VM. That is why it is off unless you ask for it.
Without "docker": true, dockerd exits with Devices cgroup isn't
mounted. The CLI also works against any daemon it can reach (DOCKER_HOST).
kosa8-universal-full
The same image plus the heavy toolchains and full browsers, for jobs that need them: .NET SDK
10.0.404, Swift 6.4.2, Julia 1.13.4, Flutter 3.50.0 with Dart 3.14, Zig 0.17.1, Kotlin 2.4.21,
sbt 2.0.12 and scala-cli 1.19.0, PowerShell 7.7.0, vcpkg, R 4.3, Erlang/OTP 25 and Elixir 1.14,
GHC 9.4 and cabal; Playwright's full Chromium, Firefox and WebKit, Cypress 16.3.0 and Puppeteer
(which uses Playwright's Chromium), and Xvfb for headed browsers. It also has the larger cloud and
scanning CLIs, left out of the universal image to keep it small: netlify 27.19.0, firebase 15.36.0,
heroku 11.13.0, doctl 2.5.0, flyctl 0.5.10, supabase 3.1.0, OpenTofu 1.13.9, Pulumi 3.276.0,
k9s 0.51.0, mongosh 2.14.2, semgrep, trivy, grype, syft and cosign. kosa8-image-check
covers its tools too.
What is left out, and why
GitHub's runner image is over 60 GiB because it carries every SDK anyone might want. A sandbox pulls its image, so this one keeps to what most jobs use. Each of these is one command away.
| Left out | Why | If you need it |
|---|---|---|
| Amp, Cursor's agent CLI | Their terms do not allow redistributing them | kosa8-install amp, kosa8-install cursor-agent |
| ngrok | A proprietary agent; use cloudflared (installed) or kosa8's own previews | kosa8-install ngrok |
| Android SDK | Its licence is yours to accept | kosa8-install android-sdk (shows the licences) |
| Ollama server | Several GiB of GPU libraries, and sandboxes have no GPU; the Python and Node clients are installed | kosa8-install ollama |
| Heavy toolchains and full browsers | Several GiB each (Swift alone is about 3.5 GiB) | Use kosa8-universal-full |
| The larger cloud CLIs (netlify, firebase, heroku, doctl, flyctl, supabase, tofu, pulumi, k9s), mongosh, and the semgrep, trivy, grype, syft and cosign scanners | About 3 GiB together, used by fewer jobs | Use kosa8-universal-full, or npm i -g netlify-cli and the like |
| Database servers | Only the clients are included; a server belongs in its own container | docker run postgres where a daemon is available, or apt-get install postgresql |
| Node 20 | End of life in April 2026 | mise use node@20 |
Size
Measured on kosa8 Cloud (build 24.04-20261115.2): 13.2 GB on disk unpacked
and 4.4 GB compressed, which is what a host pulls. A sandbox on the default 32 GB disk has
about 14 GB free; ask for more with disk_gb. kosa8-universal-full is larger
(28.3 GB unpacked, 10.1 GB compressed, 38 GB of disk in use), so it has no template: create
it by image with a bigger disk, for example
{"size": "4x8", "image": "kosa8-template/universal-full-24.04-20261115.2", "disk_gb": 64}.
A host pulls an image once per size and keeps each size's snapshot, so the pull is not paid per
sandbox: a sandbox from a universal-* template starts in a few seconds.
Tags
Published as ghcr.io/azmxai/kosa8-universal, linux/amd64 only:
| Tag | Meaning |
|---|---|
24.04-YYYYMMDD.N | One build: the Ubuntu release, the UTC build date and that day's serial, for example 24.04-20261114.1. Never overwritten. |
24.04 | The latest build. Moves; pin a dated tag in anything you depend on. |
Each published image has a CycloneDX SBOM and a build provenance attestation, which
gh attestation verify oci://ghcr.io/azmxai/kosa8-universal:<tag> --owner AzmxAI
checks.