# 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](https://docs.kosa8.com/guides/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.

---
Source: https://docs.kosa8.com/guides/cloud-images/
