Build your own environment

Every flag is a small recipe. Adding a language or tool usually takes a few lines — no image building, no registry, no compilation.

# Create a recipe

vroot recipe new mytool      # creates & opens ~/.config/vroot/recipes/mytool.conf

Save it — mytool.conf instantly becomes the -mytool flag:

vroot -mytool

# Format

name = mytool            # required, usually the file name
provides = mytool,mt     # extra flags/aliases (comma-separated)
base = alpine            # alpine | debian
packages = mytool        # space-separated pkgs; repeatable
setup =                  # shell snippet run as root during build; repeatable
env = KEY=value          # comma-separated exports
path = /opt/mytool/bin   # directories prepended to $PATH
verify = mytool -V       # must exit 0 or the build fails
description = My tool    # shown by `vroot recipe list`
docs = https://example.com

# Examples

Something available as a package

name = jq
provides = jq,json
base = alpine
packages = jq
verify = jq --version
description = jq JSON processor

Install from an upstream release (no package)

name = mytool
base = debian
packages = curl ca-certificates unzip
setup = cd /opt && curl -fsSL https://example.com/mytool-1.0-linux-x64.zip -o m.zip \
     && unzip -q m.zip && rm m.zip \
     && ln -sf /opt/mytool/bin/mytool /usr/local/bin/mytool
path = /opt/mytool/bin
verify = mytool --version
description = mytool (upstream release)

Adding a language or a framework

name = fastapi
provides = fastapi
base = alpine
packages = python3 py3-pip
setup = pip install --break-system-packages --no-cache-dir fastapi uvicorn
verify = python3 -c 'import fastapi'
description = Python + FastAPI dev shell

# Where recipes live

Location	Purpose
`recipes/*.conf` (repo)	built-in recipes
`~/.config/vroot/recipes/*.conf`	your recipes; override built-ins

Combining: pass several flags and all matching recipes merge — if any one targets debian, the whole environment uses Debian; packages, setup, env and path are concatenated; every verify must pass. Each distinct combination is cached as its own single-file image.

# Test and share

vroot recipe show mytool         # print a recipe
vroot -mytool -- mytool -V       # build (first time) and verify

# pack a whole sandbox, including your changes, into one portable image
vroot save my-sandbox mytool.sqfs
vroot mytool.sqfs                # boot it anywhere with vroot installed