Jump to content

Creating a Distrobox from a Golden Image

From Game in the Brain Wiki

Creating a Distrobox from a Golden Image

This guide explains how to build a reusable golden image from a configured Distrobox container, and how to spin up new containers from it. This is the recommended workflow for Claude Code sessions — configure once, clone many times, delete when done.

Concept

A golden image is a snapshot of a fully configured container saved as a Podman image. Instead of reinstalling Claude Code, Firejail, and your tools every session, you:

  1. Configure one container fully (the "golden" container)
  2. Commit it to a local image
  3. Spin up throwaway clones for each session
  4. Delete clones when done — the golden image stays intact

Prerequisites

Part 1: Build the Golden Image

Step 1: Configure Your Base Container

[HOST] If you do not already have a configured container, create one: 

distrobox create --name claude-base --image ubuntu:24.04

[HOST] Enter it: 

distrobox enter claude-base

[DISTROBOX] Install everything you want in the golden image: 

sudo apt update && sudo apt install -y firejail curl git
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g @anthropic-ai/claude-code

[DISTROBOX] Set up the workspace and launcher script: 

mkdir -p ~/claude_workspace
# Create run_claude.sh as described in the main workflow guide
# Then:
chmod +x ~/claude_workspace/run_claude.sh

[DISTROBOX] When everything is installed and working, exit the container: 

exit

Step 2: Stop the Container

[HOST] Distrobox containers must be stopped before committing: 

distrobox stop claude-base

Step 3: Commit to a Golden Image

[HOST] Save the container state as a named Podman image: 

podman container commit claude-base localhost/claude-golden:latest

[HOST] Verify it was created: 

podman image ls | grep claude-golden

You should see output like: 

localhost/claude-golden   latest   a1b2c3d4e5f6   2 minutes ago   1.2 GB

Step 4: (Optional) Tag a Version

If you want to keep versioned snapshots rather than overwriting latest:

[HOST] 

podman tag localhost/claude-golden:latest localhost/claude-golden:v1

Part 2: Create Containers from the Golden Image

Single Session Container

[HOST] Create a new throwaway container from the golden image: 

distrobox create --name claude-session-1 --image localhost/claude-golden:latest

[HOST] Enter it: 

distrobox enter claude-session-1

[DISTROBOX] Start working immediately — everything is pre-installed: 

cd ~/claude_workspace
./run_claude.sh

[HOST] When the session is finished, delete the container: 

distrobox rm claude-session-1

Multiple Parallel Sessions

Each session gets its own independent container. Changes in one do not affect the others.

[HOST] 

distrobox create --name claude-session-A --image localhost/claude-golden:latest
distrobox create --name claude-session-B --image localhost/claude-golden:latest
distrobox create --name claude-session-C --image localhost/claude-golden:latest

[HOST] Enter any of them independently: 

distrobox enter claude-session-A

[HOST] List all running containers at any time: 

distrobox list

[HOST] Clean up all session containers when done: 

distrobox rm claude-session-A
distrobox rm claude-session-B
distrobox rm claude-session-C

Isolated Session (Separate Home + Read-Only Host)

For full filesystem isolation, add --home and a read-only /run/host mount:

[HOST] 

mkdir -p ~/sandbox-homes/claude-session-1

distrobox create \
  --name claude-session-1 \
  --image localhost/claude-golden:latest \
  --home ~/sandbox-homes/claude-session-1 \
  --additional-flags "--mount type=bind,source=/,target=/run/host,ro"

[HOST] Enter: 

distrobox enter claude-session-1

[HOST] When done, delete both the container and its sandbox home: 

distrobox rm claude-session-1
rm -rf ~/sandbox-homes/claude-session-1

Part 3: Update the Golden Image

When you need to add tools or upgrade Claude Code across all future sessions:

[HOST] Create a temporary update container from the current golden image: 

distrobox create --name claude-update --image localhost/claude-golden:latest

[HOST] Enter it: 

distrobox enter claude-update

[DISTROBOX] Make your changes: 

npm update -g @anthropic-ai/claude-code
sudo apt install -y some-new-tool

[DISTROBOX] Exit: 

exit

[HOST] Stop, commit, and clean up: 

distrobox stop claude-update
podman container commit claude-update localhost/claude-golden:latest
distrobox rm claude-update

The golden image is now updated. All future containers created from it will have the changes.

Part 4: Back Up and Restore the Golden Image

Export to a File

[HOST] Save the golden image to a portable archive: 

podman save localhost/claude-golden:latest -o ~/claude-golden.tar

Restore from a File

[HOST] Load it back on any machine: 

podman load -i ~/claude-golden.tar

Transfer to Another Machine

[HOST] 

# On source machine — export
podman save localhost/claude-golden:latest | gzip > ~/claude-golden.tar.gz

# On destination machine — import
gunzip -c ~/claude-golden.tar.gz | podman load

Quick Reference

Task Command Where
Create base container distrobox create --name claude-base --image ubuntu:24.04 HOST
Enter container distrobox enter claude-base HOST
Stop container distrobox stop claude-base HOST
Commit to golden image podman container commit claude-base localhost/claude-golden:latest HOST
List images podman image ls HOST
Create session from golden image distrobox create --name claude-session-1 --image localhost/claude-golden:latest HOST
List all containers distrobox list HOST
Delete session container distrobox rm claude-session-1 HOST
Delete golden image podman image rm localhost/claude-golden:latest HOST
Export image to file podman save localhost/claude-golden:latest -o claude-golden.tar HOST
Import image from file podman load -i claude-golden.tar HOST

See Also

Retrieved from "http://wiki.gi7b.org/index.php?title=Creating_a_Distrobox_from_a_Golden_Image&oldid=133"