Zomg gives you instant Linux sandbox environments. Each environment is a box: a persistent, isolated Linux system you create in seconds, run commands in, snapshot, and reach over the network. You drive Zomg with the zomg CLI, which talks to a server called zomg-api. The server manages the underlying Kubernetes and filesystem state so you work with boxes, not infrastructure.
The user-facing noun for a sandbox is box. The --fork flag is reserved for one action: clone an existing box’s filesystem into a new box.

​
The mental model

You create a box, run commands in it, and reach it over the web. It behaves like a fresh Linux machine: install packages, edit files, start services. The default base is box-base (built on Ubuntu 24.04 with a standard toolbox preinstalled), and anything you write survives across stops and resumes. Publish a port and the box gets a real URL at https://<name>.zomg.ai.

​
Persistent filesystems

Zomg keeps box state as copy-on-write btrfs snapshots. The layers build on each other:
LayerRole
basesRead-only template subvolumes. A new box starts from a base.
rootsWritable btrfs snapshots created from a base — your box’s live root.
checkpointsRoot snapshots you capture and restore.
volumes, volume-checkpoints, volume-backupsData-volume state for disks you mount into boxes.
Because roots are snapshots of a base, creating a box is fast: you get a writable copy of a template without duplicating it.

​
The zomg-api server

zomg-api is an HTTP server that owns the Kubernetes and btrfs state and serves interactive transports:
  • REST routes under /v1/projects/{project}/boxes/{name} for box lifecycle.
  • WebSocket exec at …/exec/ws and console at …/console for running commands and attaching an interactive terminal. A non-WebSocket POST …/exec is also available.
For running commands inside a box, the server prefers a container-runtime path and falls back to Kubernetes exec. See the API reference for the full route surface.

​
Reaching boxes

Publishing a box port gives it a stable HTTPS hostname: 
https://<name>.zomg.ai
Here zomg.ai is your instance’s domain — the same one you used when connecting the CLI.
The publish name comes from --as <NAME> (or is generated when omitted) and is independent of the box’s project.

​
Box-to-box networking

Boxes in the same project reach each other over DNS without publishing anything. Box Services are headless, so a box name resolves directly to the pod and any port is reachable:
  • Same project: reach another box by its bare name.
  • Different project: reach it by name.project.
Publishing is only for exposing a box to the public internet. In-cluster, box-to-box traffic needs no publishing.

​
Common commands

Once the CLI is connected to your instance, the everyday workflow is: 
# Create a box from the default base
zomg create myapp

# Run a command in it
zomg exec myapp -- echo hello

# List your boxes
zomg list

# Open an interactive console
zomg console myapp

# Delete it
zomg delete myapp
A few flags worth knowing on zomg create:
  • --base / -b — start from a specific base (default base is box-base).
  • --fork / -f — clone an existing box’s filesystem instead of a base (cannot combine with --base).
  • --data / -d — mount a data volume as NAME=/path[:ro|:rw].
  • --env / -e, --cpu, --memory, --project / -p.
These docs are also served per deployment as a docs pack at https://docs.zomg.ai.

​
Projects

Boxes live in a project. The CLI resolves the project in this order:
  1. --project / -p flag
  2. ZOMG_PROJECT environment variable (set automatically inside every box)
  3. The current git repository’s top-level directory name
There is no fallback project: if none of these applies, the command errors with no project: pass --project <name>, set ZOMG_PROJECT, or run inside a git repository. You can address a box in another project with project:box (canonical) or project.box (shorthand).

​
Where to next

Quickstart

Create your first box, run commands in it, and publish a page.

Boxes

The box lifecycle: create, exec, stop, resume, delete.

Environment

The runtime inside a box: filesystem layout, PID 1, DNS, and injected env vars.

Snapshots and bases

Capture box state as checkpoints and turn it into reusable bases.

Data volumes

Persistent disks you mount into one or more boxes.

Services

Run long-lived services and expose them at a public URL.