Pixel-CLI/pixel / .agents/skills/docker-setup-smoke
docker-setup-smoke
VerifiedReplay Pixel's new-user setup in Docker without an LLM — install through a release archive, install.sh, the Homebrew tap, or sources from main, a PR head or a pinned commit; then personal Claude/Codex/pi settings kept, idempotent reinstall, first pixel audit, doctor and --fix, project install, disabled classify and uninstall; with --agents, Claude Code, Codex and pi sessions against a scripted fake model show whether each receives the Pixel prompt, runs pixel and routes grep. Use for Linux setup smoke checks, not macOS behavior or real model inference.
Docker setup smoke
Run a Linux binary with a fresh non-root user, pre-existing personal agent settings and a small Git repository. Docker Desktop on macOS works; the tests still exercise Linux. No Docker Agentic Platform or model key is needed.
From the repository root:
sh .agents/skills/docker-setup-smoke/scripts/run.sh
# Another published release archive:
sh .agents/skills/docker-setup-smoke/scripts/run.sh v0.6.1
# The published install.sh, into a dedicated directory:
sh .agents/skills/docker-setup-smoke/scripts/run.sh --installer
# The Homebrew tap on Linuxbrew:
sh .agents/skills/docker-setup-smoke/scripts/run.sh --brew
# Compile current upstream main:
sh .agents/skills/docker-setup-smoke/scripts/run.sh --source main
# Compile a PR's head, including a fork PR (not GitHub's merge ref):
sh .agents/skills/docker-setup-smoke/scripts/run.sh --pr 427
# Replay the exact source SHA recorded by a prior run:
sh .agents/skills/docker-setup-smoke/scripts/run.sh --source <40-character-SHA>
# Any of the above, then agent sessions against the fake model:
sh .agents/skills/docker-setup-smoke/scripts/run.sh --agents --source main
Binary modes
- Release archive (default
v0.6.1): download that exact release's architecture-specific archive and verify its published SHA-256. --installer: fetchreleases/latest/download/install.shand run it as the test user withPIXEL_INSTALL_DIR=$HOME/opt/pixel/bin. The installer always resolves the latest release, so this mode tests whatever that is on the day;binary-version.txtandinstaller.logrecord which one.--brew:brew install LivioGama/tap/pixelin the pinnedhomebrew/brewimage, latest formula. Homebrew's prefix is private to itslinuxbrewuser, so that user runs the checks; uninstall must leave the Cellar binary to Homebrew.brew-deps.txtlists what the formula pulled in, andbrew-host.txtwhether Homebrew judges the host's glibc or libstdc++ older than its CI's: then it gives every formula, bottled or not, an implicitgccandglibc. A control formula with no dependency (local/smoke/control) measures what the host adds (brew-host-deps.txt); a dependency of pixel beyond it fails the run. The image (Ubuntu 22.04, glibc 2.35) is such a host: its 12 are the control's, and aNOTEsays so.- Source (
--source,--pr): fetch fromhttps://github.com/Pixel-CLI/pixel.gitinside the container, check out the fetched commit detached, and build with pinned Rust 1.98.1,--locked --no-default-features --features model2vec, debug profile without debug info: this tests setup contracts, not release performance or musl compatibility. The checkout and build directory are discarded; each run is a cold build of several minutes.pixel --versionmust report the fetched SHA.
What checks.sh asserts
- Personal settings exist before Pixel:
~/.claude/settings.json(model, permissions, aPreToolUseEdit|Write hook and aSessionStarthook),~/.claude/CLAUDE.md,~/.codex/config.toml,~/.codex/hooks.jsonwith a user hook,~/.codex/AGENTS.md,~/.pi/agent/{settings.json,AGENTS.md,APPEND_SYSTEM.md}. - Global install keeps every personal key, hook and instruction line.
- A second global install leaves every managed file byte-identical (backups excluded).
- Metrics configuration persists without an env override.
- First
pixel auditin a never-indexed repository printsno code graph yet, building it (first run only)on stderr, reports coverage (indexed: python 4/4) and file counts; the second run does not rebuild. pixel doctor --fail-on yellowfails in a never-prepared repository, every[red]line is followed by afix:line, and after--fixno check is red. The only yellow allowed then isinstall.codex-hook-review/repo.codex-hook-reviewnaming/hooks: Codex runs a hook only after the user reviews it, which no command can do for them.- Project install keeps
AGENTS.mduser instructions and is repeatable; disabled classify fails with empty stdout and the disabled diagnostic; project uninstall restoresAGENTS.mdbyte for byte. - Global uninstall restores the personal JSON files to equal values and the text files byte for byte, removes the prompt and a binary pixel owns (not a Homebrew one), and a second uninstall succeeds.
- Files left behind that the user did not have before are listed in
residue.txtand counted in aNOTEline, not failed. Its*.pixel-bak.*files must be exactly those the last uninstall'sbackupsstep names in itsrm --command (read back withshlex), and the only other file~/.pixel/config.yaml, whichpixel config --globalwrote; a release without that step gets aNOTEinstead.
A personal PreToolUse hook matching Bash makes pixel setup --repo skip the
Claude guard (yellow claude guard not installed); the fixture matches
Edit|Write so the guard is installed. The checks add such a hook for one extra
project copy (then restore settings.json byte for byte): the install step must
name the hook and what to do (narrow its matcher, or work without the guard),
and repo.claude-hooks must be yellow with the same advice and no fix: line;
a release without that advice gets a NOTE.
Agent sessions (--agents)
The image then also carries Node and pinned agent CLIs (node_version and
agent_packages in run.sh: Node v24.21.0, Claude Code 2.1.285, Codex 0.159.2,
pi 0.99.1). After checks.sh, agents.sh reinstalls Pixel over the restored
personal settings, installs it in a copy of the project, and runs one
non-interactive session per agent: claude -p, codex exec, pi --print.
No model or key is involved. fake-llm.py listens on 127.0.0.1:8765 inside the
container and speaks Anthropic Messages (Claude Code, and pi through a
models.json provider) and OpenAI Responses (Codex through -c model_providers.smoke=…). It plays a fixed script: call the agent's shell tool
with pixel search-content -F helper_1 src, then with grep -rn helper_1 src,
then answer FAKE_LLM_DONE. Every request is logged to
<agent>-requests.jsonl, which is the evidence of what the agent sent a model.
The project is trusted the way a user accepting the prompt would: a Codex
projects."<path>".trust_level="trusted" override and pi --approve. Without
it, neither loads project-level configuration.
Asserted per agent: exit and final answer, the Pixel prompt in the first model
request (deterministic repository facts, the agent prompt's heading, for Claude's SessionStart context,
pixel:managed:begin for Codex developer instructions and pi's
APPEND_SYSTEM.md), both tool results fed back, and a new search-content row
in the project's .pixel/actions.jsonl from the model's pixel call. Reported,
not asserted:
- Claude: whether the guard routed the native
grep(a newsearch-like-rgrow), and whether the prompt arrived only as a<persisted-output>preview because the hook output exceeded Claude Code's 10 000-character inline limit. - Codex: how many Pixel hooks ran (
run-hook … --provider codexrows), then a second session with--dangerously-bypass-hook-truststanding in for the user's/hooksreview, which tells an unreviewed hook from a broken one. - pi: the guard's last
bashdecision in.pixel/pi-policy.jsonlunder the default policy, then again underpixel config policy enforce. pi's guard blocks rather than reroutes, so it never writessearch-like-rgrows.
A scripted model shows the harness wiring — prompt delivery, hooks, guards, the binary on the agent's PATH — not whether a real model follows the prompt.
Environment and isolation
scripts/Dockerfile holds the environment only: the pinned base image, curl,
Git, Python and the tester user. The runner builds it without a build context
as pixel-setup-smoke:<mode>; Docker's layer cache skips the apt step after the
first run. Fetching or compiling pixel and the checks stay in docker run, so a
failed step still leaves a container to export evidence from and a moving ref
such as main is never served from a cache. The cached apt layer keeps the
packages of its first build: remove the image (docker image rm pixel-setup-smoke:<mode>) to refresh them or reclaim space.
Only this skill's scripts are mounted, read-only. Host home, project, credentials and Docker socket are not mounted. The runner removes its own container on completion or interruption, never prunes other resources, and leaves the base and smoke images cached.
Evidence and limits
The runner prints a directory under target/docker-setup-smoke/ containing the
checkout SHA, Docker version, base image digest, built image ID, test user,
invocation, binary provenance, image build log, complete run log and exit status,
plus every JSON report, audit and doctor output, the personal-settings snapshot
and the residue list, exported before container removal, including on failure.
Report the tested binary's version and commit separately from the runner checkout
SHA. Source mode tests fetched upstream code, not uncommitted local changes.
Not covered: macOS (Homebrew on macOS included), shells other than bash, interactive setup and agent TUIs, real model inference or a model's compliance.
Prerequisites: a POSIX sh, Git, a running Docker engine with BuildKit (Docker Desktop's
default) and network access to GitHub, Docker Hub and crates.io, plus Debian or
Ubuntu mirrors until the smoke image is cached. The image build is not
time-bounded; bootstrap is bounded to 5 minutes (release, installer), 15 minutes
(brew) or 30 minutes (source), checks to 5 minutes and agent sessions to 10.
--agents also needs nodejs.org and the npm registry until its image is cached.
CPU/memory limits are 4 CPUs/6 GiB.
On failure inspect the saved evidence and fix the cause before replaying.
When changing the runner, run python3 scripts/test-runner.py from this skill
directory and ShellCheck on its shell scripts. The contract tests verify mode
selection, invalid-selector rejection, failed-build and failed-run evidence and
the fake model's script in both wire formats without Docker; also replay the lifecycle in Docker for the modes affected by the
change.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |