Skip to content

Pixel-CLI/pixel / .agents/skills/docker-setup-smoke

docker-setup-smoke

Verified

Replay 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: fetch releases/latest/download/install.sh and run it as the test user with PIXEL_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.txt and installer.log record which one.
  • --brew: brew install LivioGama/tap/pixel in the pinned homebrew/brew image, latest formula. Homebrew's prefix is private to its linuxbrew user, so that user runs the checks; uninstall must leave the Cellar binary to Homebrew. brew-deps.txt lists what the formula pulled in, and brew-host.txt whether Homebrew judges the host's glibc or libstdc++ older than its CI's: then it gives every formula, bottled or not, an implicit gcc and glibc. 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 a NOTE says so.
  • Source (--source, --pr): fetch from https://github.com/Pixel-CLI/pixel.git inside 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 --version must report the fetched SHA.

What checks.sh asserts

  1. Personal settings exist before Pixel: ~/.claude/settings.json (model, permissions, a PreToolUse Edit|Write hook and a SessionStart hook), ~/.claude/CLAUDE.md, ~/.codex/config.toml, ~/.codex/hooks.json with a user hook, ~/.codex/AGENTS.md, ~/.pi/agent/{settings.json,AGENTS.md,APPEND_SYSTEM.md}.
  2. Global install keeps every personal key, hook and instruction line.
  3. A second global install leaves every managed file byte-identical (backups excluded).
  4. Metrics configuration persists without an env override.
  5. First pixel audit in a never-indexed repository prints no 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.
  6. pixel doctor --fail-on yellow fails in a never-prepared repository, every [red] line is followed by a fix: line, and after --fix no check is red. The only yellow allowed then is install.codex-hook-review / repo.codex-hook-review naming /hooks: Codex runs a hook only after the user reviews it, which no command can do for them.
  7. Project install keeps AGENTS.md user instructions and is repeatable; disabled classify fails with empty stdout and the disabled diagnostic; project uninstall restores AGENTS.md byte for byte.
  8. 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.
  9. Files left behind that the user did not have before are listed in residue.txt and counted in a NOTE line, not failed. Its *.pixel-bak.* files must be exactly those the last uninstall's backups step names in its rm -- command (read back with shlex), and the only other file ~/.pixel/config.yaml, which pixel config --global wrote; a release without that step gets a NOTE instead.

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 new search-like-rg row), 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 codex rows), then a second session with --dangerously-bypass-hook-trust standing in for the user's /hooks review, which tells an unreviewed hook from a broken one.
  • pi: the guard's last bash decision in .pixel/pi-policy.jsonl under the default policy, then again under pixel config policy enforce. pi's guard blocks rather than reroutes, so it never writes search-like-rg rows.

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.

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: 466kUpdated Claude CodeCodexVerifiedInstall
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: 466kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall