grow-box
Getting started

Getting started

Run a project's checks in a throwaway VM, a container, or a host you already have, using Grow Box's launchers.

Each launcher does the same four things on a different kind of machine: make or reach it, install the tools, clone your repositories, and run your command. You tell it what to clone and what to run with environment variables.

DANGER

Point Grow Box only at machines made for it. launch-remote.sh installs packages on the host, adds your user to the docker group, clones into your home folder and links under /opt. The command you give it runs with your repositories' keys in place, and it is printed in the log as written, so never put a secret in it.

Get the scripts

git clone https://github.com/open-tomato/grow-box.git
cd grow-box
bash tests/run.sh

The tests replace every remote command with a stand-in, so they run anywhere bash runs. The last line reads ── total: 169 passed, 0 failed ── at this version.

Say what to clone and what to run

Variable	What it holds
`SANDBOX_REPOS`	the repositories, as rows `owner\|repo\|optname`, separated by newlines or commas; each is cloned to `~/<optname>` and linked at `/opt/<optname>`
`SANDBOX_RUN_CMD`	the command to run once the repositories are in place; unset, nothing runs
`SANDBOX_RUN_DIR`	where it runs; by default `/opt/<optname>` of the first row

To clone, Grow Box registers a read-only deploy key, an SSH key that can read one repository and nothing else, on each repository. It uses GH_TOKEN for that, or the token of a signed-in GitHub CLI. That token stays on your machine. With no repositories set, nothing is cloned and no credentials are staged.

A throwaway VM

You need multipass. This launches an Ubuntu 24.04 VM named growbox-sandbox, installs the tools, clones the repository and runs its tests:

SANDBOX_REPOS='your-org|your-repo|your-repo' \
SANDBOX_RUN_CMD='bun install && bun test' \
bash tools/sandbox/launch-vm.sh

[verify: not run for this page; it creates a VM and registers deploy keys on a real repository.]

Run it again after a failure, or after changing a script, and it converges: it does only what is missing. These flags, from launch-vm.sh --help, cover the rest of a VM's life:

Flag	What it does
`--no-run`	prepare the VM, skip the command
`--branch NAME`	check out this branch in the cloned repositories (default `main`)
`--regenerate`	delete the VM, check it is gone, and build it again with the same flags
`--destroy`	delete the VM
`--cleanup`	delete the deploy keys this tool created

WARN

Running launch-vm.sh with no argument builds the VM; it does not print help. Use --help to read the usage.

The VM gets multipass's default size, because the launcher sets no CPU, memory or disk. [verify: the default size was read from the script and the size spec, not measured.]

A quick check in a container

With Docker running, from the repository root:

docker compose -f tools/sandbox/compose.quick.yaml up -d
docker compose -f tools/sandbox/compose.quick.yaml exec sandbox bash
docker compose -f tools/sandbox/compose.quick.yaml down -v

The sandbox container has the tools, and the Grow Box clone you run it from is mounted at /work. It reads none of the SANDBOX_* variables above, so it clones nothing and runs no command of its own. Beside it runs a separate Docker daemon, so checks that need one work without touching your own. That daemon runs privileged, which a Docker daemon inside a container needs. Checks that need a whole machine belong in the VM. [verify: not run for this page; it builds an image and starts a privileged container.]

A host you already have

launch-remote.sh does the same on a machine you reach as ssh <name>:

SANDBOX_REPOS='your-org|your-repo|your-repo' \
SANDBOX_RUN_CMD='bun install && bun test' \
bash tools/sandbox/launch-remote.sh --name sandbox-box --ip 192.0.2.10

[verify: not run for this page; it changes the host it points at.]

--name is the SSH alias and --ip the host's address; both are required. On a host where sudo asks for a password, you are asked several times, or --nopasswd-sudo installs a temporary rule that is removed at the end. --reset deletes the clones, keys and .npmrc Grow Box wrote, and --purge --confirm purge also removes Docker.

Keys and tokens

When deploy keys cannot be registered, the run stops. SANDBOX_ALLOW_TOKEN_FALLBACK=1 lets it clone with a token instead, and that token is copied to the box and stays there until a reset. The token of a signed-in GitHub CLI is never copied.

--ssh-key PATH copies a private key to the box, so git can push from it. When it is set, the box clones with that key and no deploy key is registered. Use a key made for the sandbox, one you can revoke, never your main key.