container-layer
Authors and caches a personalized container environment from a Dockerfile- like spec, as a single layer or as a composition of independently cached layers. Use when the user mentions "container layer", "Containerfile", "custom container", "cache my installs", "composable layers",
Install
npx skills add https://github.com/oaustegard/claude-skills/tree/main/plugins/environment-and-config/skills/container-layer
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oaustegard-claude-skills@llmmart
git clone https://github.com/oaustegard/claude-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oaustegard/claude-skills collection as a plugin from our marketplace. Git is the plain clone.
README
container-layer
Custom, cached environment overlays for Claude's ephemeral containers.
What This Does
Claude.ai and Claude Code on the Web run in ephemeral containers — every session starts from a blank slate. This skill lets you declare your environment in a Containerfile (a Dockerfile subset), build it once, cache the result as a tarball in GitHub Releases, and restore it in seconds on subsequent sessions.
First session: parse Containerfile → execute instructions → snapshot filesystem delta → push ~3 MB tarball to GitHub Releases.
Every session after: download tarball → extract → done. One fetch replaces N installs.
Components
| File | Purpose |
|---|---|
SKILL.md |
Skill metadata and documentation |
Containerfile |
Default environment spec (edit this) |
boot.sh |
Boot script for Claude.ai project instructions |
boot-ccotw.sh |
Boot script for Claude Code (SessionStart hook) |
scripts/containerfile.py |
Parser + executor with baseline diffing |
scripts/layer_cache.py |
GitHub Releases tarball cache |
scripts/cli.py |
CLI: build, restore, hash, inspect |
scripts/uv_shim.sh |
Captures ad-hoc uv pip install to Containerfile |
Supported Instructions
FETCH github:user/repo /dest # GitHub repo tarball
FETCH github:user/repo@ref /dest # Specific ref
RUN uv pip install --system pandas # Shell commands
ENV KEY=value # Environment variables
WORKDIR /path # Working directory
SNAPSHOT /path # Include in cached layer
FROM, EXPOSE, CMD, ENTRYPOINT, etc. are silently ignored (Dockerfile compatibility).
Smart Snapshotting
The executor captures a filesystem baseline before building, then diffs against it — only new files from pip install / uv pip install are included in the tarball, not the entire dist-packages directory. FETCH destinations are captured in full. This keeps tarballs small (~3 MB for a full skills repo + Python packages).
Cache Invalidation
The cache key is a SHA-256 of the Containerfile contents. Pass --invalidate-on user/repo to include a GitHub repo's HEAD SHA in the key — when that repo gets a new commit, the cache auto-invalidates and triggers a rebuild.
python3 -m scripts.cli --invalidate-on oaustegard/claude-skills restore ./Containerfile
Ad-Hoc Install Capture
Source the uv shim to automatically append new installs to your Containerfile:
source ./scripts/uv_shim.sh ./Containerfile
uv pip install --system pandas # installs AND appends RUN line
Test Repo
See container-layer-test for a working example with Claude Code on the Web SessionStart hooks.
Skill manifest
Container Layer
Build a reproducible, cached environment overlay for ephemeral containers using a Dockerfile-like spec.
When NOT to use this skill
This authors and caches a layer spec. It is not a Docker troubleshooting tool.
| Situation | Use |
|---|---|
| A build is slow or failing | read the build log; this skill will not help |
| Managing a running container | docker/podman directly |
| Session boot sequence and hooks | the workspace's own boot docs |
The tell is tense: this skill is for the environment you want next session, not the container you are fighting now.
Concept
The container resets every session, but your environment shouldn't. This skill:
- Parses a
Containerfile(Dockerfile subset) that declares your environment - Caches the built result as a tarball in GitHub Releases
- Restores from cache on subsequent boots (single fetch vs. N installs)
- Provides a
uvshim that captures ad-hoc installs back into the Containerfile
Supported Containerfile Instructions
# Environment variables
ENV KEY=value
# Shell commands (including package installs)
RUN apt-get install -y foo # system packages
RUN uv pip install pandas numpy # Python packages (preferred)
RUN pip install requests # also works
# Fetch files from URLs or GitHub
FETCH https://example.com/file.tar.gz /dest/path
FETCH github:user/repo /dest/path # latest tarball
FETCH github:user/repo@ref /dest/path # specific ref
# Set working directory for subsequent RUN commands
WORKDIR /some/path
# Declare paths to include in the cached layer snapshot
# (auto-detected for FETCH destinations and pip/uv installs)
SNAPSHOT /additional/path/to/capture
# Ignored (Dockerfile compat, no-op here):
# FROM, EXPOSE, CMD, ENTRYPOINT, LABEL, ARG, VOLUME, USER, SHELL
Usage
Single layer — build / restore
from scripts.containerfile import ContainerLayer
layer = ContainerLayer(
containerfile_path="/path/to/Containerfile",
cache_repo="oaustegard/claude-container-layers", # GitHub repo for release assets
gh_token="...",
)
# Try cache first, fall back to full build
layer.restore_or_build()
Or via CLI:
python -m scripts.cli restore /path/to/Containerfile --repo user/cache-repo
Multi-layer composition (v0.2.0+)
Decompose a heavy environment into named layers, each cached independently. Compose them in order on session start so most-changed bits don't invalidate stable bits.
from scripts.containerfile import compose
compose(
containerfile_paths=[
"layers/Containerfile", # name='base' (always-on)
"layers/Containerfile.scientific", # name='scientific'
"layers/Containerfile.mojo", # name='mojo'
],
cache_repo="user/cache-repo",
)
Each layer gets its own cache release tag layer-<name>-<hash> so retention policies (keep last N) and cache invalidation operate per-name.
Default layer names are derived from the Containerfile path:
Containerfile→baseContainerfile.scientific→scientificlayers/Containerfile.X→X
CLI equivalent:
python -m scripts.cli compose \
layers/Containerfile \
layers/Containerfile.scientific \
layers/Containerfile.mojo \
--repo user/cache-repo
Per-layer name override
If filename doesn't derive cleanly, pass --name NAME:PATH per layer:
python -m scripts.cli compose \
--name base:weird-named-file.txt \
--name mojo:other-file.txt \
weird-named-file.txt other-file.txt
Single-layer naming (back-compat)
build / restore / hash / inspect accept --name:
python -m scripts.cli restore Containerfile.mojo --name mojo
# Cache tag becomes 'layer-mojo-<hash>' instead of 'layer-<hash>'.
# Omit --name to keep the old back-compat tag for existing callers.
The uv Shim
After building, install the shim to capture future installs:
source /path/to/container-layer/scripts/uv_shim.sh /path/to/Containerfile
Now uv pip install foo both installs the package AND appends RUN uv pip install foo to your Containerfile.
Rebuilding the Cache
After modifying the Containerfile:
layer.build_and_push() # Execute, snapshot, upload
Architecture
Read scripts/containerfile.py for the parser/executor and scripts/layer_cache.py for the GitHub Releases caching logic. The cache key is a SHA-256 of the Containerfile contents — any change triggers a rebuild.
Configuration
The skill expects these environment variables (or pass as constructor args):
GH_TOKEN— GitHub token withreposcope (for releases)- Cache repo can be any repo the token has write access to
Workflow Integration
This skill is designed to be invoked from a boot script. Example Containerfile:
# Skills
FETCH github:oaustegard/claude-skills /mnt/skills/user
# Python environment
RUN uv pip install --system pandas numpy requests
# Path config
RUN echo '/mnt/skills/user/remembering' > /usr/local/lib/python3.12/dist-packages/muninn-remembering.pth
# Custom setup
ENV MY_VAR=hello
WORKDIR /home/claude
Files (claude-skills)
-
scripts
-
cli.py 8.1 KB
Loading… -
containerfile.py 20 KB
Loading… -
layer_cache.py 8.4 KB
Loading… -
test_baseline_paths.py 4.9 KB
Loading… -
test_named_layers.py 6.6 KB
Loading… -
uv_shim.sh 2.5 KB
Loading… -
__init__.py 26 B
Loading… -
__main__.py 30 B
Loading…
-
-
boot-ccotw.sh 2.7 KB
Loading… -
boot.sh 2.9 KB
Loading… -
CHANGELOG.md 4.3 KB
Loading… -
Containerfile 1.4 KB · in bundle
-
README.md 2.8 KB
# container-layer Custom, cached environment overlays for Claude's ephemeral containers. ## What This Does Claude.ai and Claude Code on the Web run in ephemeral containers — every session starts from a blank slate. This skill lets you declare your environment in a `Containerfile` (a Dockerfile subset), build it once, cache the result as a tarball in GitHub Releases, and restore it in seconds on subsequent sessions. **First session:** parse Containerfile → execute instructions → snapshot filesystem delta → push ~3 MB tarball to GitHub Releases. **Every session after:** download tarball → extract → done. One fetch replaces N installs. ## Components | File | Purpose | |------|---------| | `SKILL.md` | Skill metadata and documentation | | `Containerfile` | Default environment spec (edit this) | | `boot.sh` | Boot script for Claude.ai project instructions | | `boot-ccotw.sh` | Boot script for Claude Code (SessionStart hook) | | `scripts/containerfile.py` | Parser + executor with baseline diffing | | `scripts/layer_cache.py` | GitHub Releases tarball cache | | `scripts/cli.py` | CLI: `build`, `restore`, `hash`, `inspect` | | `scripts/uv_shim.sh` | Captures ad-hoc `uv pip install` to Containerfile | ## Supported Instructions ```dockerfile FETCH github:user/repo /dest # GitHub repo tarball FETCH github:user/repo@ref /dest # Specific ref RUN uv pip install --system pandas # Shell commands ENV KEY=value # Environment variables WORKDIR /path # Working directory SNAPSHOT /path # Include in cached layer ``` `FROM`, `EXPOSE`, `CMD`, `ENTRYPOINT`, etc. are silently ignored (Dockerfile compatibility). ## Smart Snapshotting The executor captures a filesystem baseline before building, then diffs against it — only new files from `pip install` / `uv pip install` are included in the tarball, not the entire `dist-packages` directory. `FETCH` destinations are captured in full. This keeps tarballs small (~3 MB for a full skills repo + Python packages). ## Cache Invalidation The cache key is a SHA-256 of the Containerfile contents. Pass `--invalidate-on user/repo` to include a GitHub repo's HEAD SHA in the key — when that repo gets a new commit, the cache auto-invalidates and triggers a rebuild. ```bash python3 -m scripts.cli --invalidate-on oaustegard/claude-skills restore ./Containerfile ``` ## Ad-Hoc Install Capture Source the uv shim to automatically append new installs to your Containerfile: ```bash source ./scripts/uv_shim.sh ./Containerfile uv pip install --system pandas # installs AND appends RUN line ``` ## Test Repo See [container-layer-test](https://github.com/oaustegard/container-layer-test) for a working example with Claude Code on the Web SessionStart hooks. -
SKILL.md 5.7 KB
--- name: container-layer description: >- Authors and caches a personalized container environment from a Dockerfile- like spec, as a single layer or as a composition of independently cached layers. Use when the user mentions "container layer", "Containerfile", "custom container", "cache my installs", "composable layers", "uv shim", or wants package installations, skills and environment config to survive an ephemeral session. Also for snapshotting, restoring or rebuilding that environment, and for capturing ad-hoc installs into a reproducible spec. metadata: version: 0.4.0 --- # Container Layer Build a reproducible, cached environment overlay for ephemeral containers using a Dockerfile-like spec. ## When NOT to use this skill This authors and caches a layer spec. It is not a Docker troubleshooting tool. | Situation | Use | |---|---| | A build is slow or failing | read the build log; this skill will not help | | Managing a running container | docker/podman directly | | Session boot sequence and hooks | the workspace's own boot docs | The tell is tense: this skill is for the environment you want next session, not the container you are fighting now. ## Concept The container resets every session, but your environment shouldn't. This skill: 1. Parses a `Containerfile` (Dockerfile subset) that declares your environment 2. Caches the built result as a tarball in GitHub Releases 3. Restores from cache on subsequent boots (single fetch vs. N installs) 4. Provides a `uv` shim that captures ad-hoc installs back into the Containerfile ## Supported Containerfile Instructions ```dockerfile # Environment variables ENV KEY=value # Shell commands (including package installs) RUN apt-get install -y foo # system packages RUN uv pip install pandas numpy # Python packages (preferred) RUN pip install requests # also works # Fetch files from URLs or GitHub FETCH https://example.com/file.tar.gz /dest/path FETCH github:user/repo /dest/path # latest tarball FETCH github:user/repo@ref /dest/path # specific ref # Set working directory for subsequent RUN commands WORKDIR /some/path # Declare paths to include in the cached layer snapshot # (auto-detected for FETCH destinations and pip/uv installs) SNAPSHOT /additional/path/to/capture # Ignored (Dockerfile compat, no-op here): # FROM, EXPOSE, CMD, ENTRYPOINT, LABEL, ARG, VOLUME, USER, SHELL ``` ## Usage ### Single layer — build / restore ```python from scripts.containerfile import ContainerLayer layer = ContainerLayer( containerfile_path="/path/to/Containerfile", cache_repo="oaustegard/claude-container-layers", # GitHub repo for release assets gh_token="...", ) # Try cache first, fall back to full build layer.restore_or_build() ``` Or via CLI: ```bash python -m scripts.cli restore /path/to/Containerfile --repo user/cache-repo ``` ### Multi-layer composition (v0.2.0+) Decompose a heavy environment into named layers, each cached independently. Compose them in order on session start so most-changed bits don't invalidate stable bits. ```python from scripts.containerfile import compose compose( containerfile_paths=[ "layers/Containerfile", # name='base' (always-on) "layers/Containerfile.scientific", # name='scientific' "layers/Containerfile.mojo", # name='mojo' ], cache_repo="user/cache-repo", ) ``` Each layer gets its own cache release tag `layer-<name>-<hash>` so retention policies (keep last N) and cache invalidation operate per-name. Default layer names are derived from the Containerfile path: - `Containerfile` → `base` - `Containerfile.scientific` → `scientific` - `layers/Containerfile.X` → `X` CLI equivalent: ```bash python -m scripts.cli compose \ layers/Containerfile \ layers/Containerfile.scientific \ layers/Containerfile.mojo \ --repo user/cache-repo ``` ### Per-layer name override If filename doesn't derive cleanly, pass `--name NAME:PATH` per layer: ```bash python -m scripts.cli compose \ --name base:weird-named-file.txt \ --name mojo:other-file.txt \ weird-named-file.txt other-file.txt ``` ### Single-layer naming (back-compat) `build` / `restore` / `hash` / `inspect` accept `--name`: ```bash python -m scripts.cli restore Containerfile.mojo --name mojo # Cache tag becomes 'layer-mojo-<hash>' instead of 'layer-<hash>'. # Omit --name to keep the old back-compat tag for existing callers. ``` ### The uv Shim After building, install the shim to capture future installs: ```bash source /path/to/container-layer/scripts/uv_shim.sh /path/to/Containerfile ``` Now `uv pip install foo` both installs the package AND appends `RUN uv pip install foo` to your Containerfile. ### Rebuilding the Cache After modifying the Containerfile: ```python layer.build_and_push() # Execute, snapshot, upload ``` ## Architecture Read `scripts/containerfile.py` for the parser/executor and `scripts/layer_cache.py` for the GitHub Releases caching logic. The cache key is a SHA-256 of the Containerfile contents — any change triggers a rebuild. ## Configuration The skill expects these environment variables (or pass as constructor args): - `GH_TOKEN` — GitHub token with `repo` scope (for releases) - Cache repo can be any repo the token has write access to ## Workflow Integration This skill is designed to be invoked from a boot script. Example Containerfile: ```dockerfile # Skills FETCH github:oaustegard/claude-skills /mnt/skills/user # Python environment RUN uv pip install --system pandas numpy requests # Path config RUN echo '/mnt/skills/user/remembering' > /usr/local/lib/python3.12/dist-packages/muninn-remembering.pth # Custom setup ENV MY_VAR=hello WORKDIR /home/claude ```
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.