Skip to content

AGENTS.md

Latest commit

 

History

History
105 lines (81 loc) · 6.94 KB

AGENTS.md

File metadata and controls

105 lines (81 loc) · 6.94 KB

AGENTS.md

This file is the working agreement for changes in this repository.

Workflow

Default workflow for this repo:

  1. Make the requested code or docs change directly.
  2. Verify it thoroughly.
  3. Commit the change before finishing.

Do not stop at unit tests when behavior can be exercised for real. If a change affects runtime behavior, flags, mounts, image builds, config loading, or release automation, run the actual path and verify the output.

If full end-to-end verification is blocked by the environment, state exactly what was run, what was not run, and why.

Any hard-earned lesson that changes how future work should be done belongs in AGENTS.md.

Build Commands

make build          # Build the yolobox binary
make test           # Run unit tests
make lint           # Run go vet (and golangci-lint if installed)
make image          # Build the Docker base image
make smoke-test     # Run smoke tests on container tools
make install        # Build and install to ~/.local/bin
make clean          # Remove built binary

Verification Standard

For non-trivial code changes, start here:

make clean && make build && make test
./yolobox version
./yolobox help
./yolobox config

Then run the feature you changed end-to-end. Examples:

  • Runtime or mount behavior: ./yolobox run ...
  • Docker integration: ./yolobox run --docker docker version
  • Custom image flow: ./yolobox run --packages cowsay /usr/games/cowsay hello
  • Config loading: ./yolobox config

For Dockerfile or image changes, rebuild the image and run container smoke tests:

make image
./yolobox run echo hello
./yolobox run whoami
./yolobox run pwd

For docs-only changes, inspect the diff carefully. Tests are optional unless the docs describe behavior that also changed.

Code Map

Most logic lives in cmd/yolobox/main.go.

Areas to check when adding flags or config:

  • Config
  • parseBaseFlags
  • mergeConfig
  • printConfig
  • saveGlobalConfig
  • runSetup
  • the runtime path that consumes the option

Also update README.md when user-facing behavior changes.

Hard Learnings

  • Named volumes shadow image contents. Anything baked into /home/yolo disappears behind yolobox-home for existing users.
  • On macOS, Docker socket source paths are resolved inside the Docker VM. Use /var/run/docker.sock as the mount source, not host-side paths like ~/.colima/default/docker.sock.
  • On macOS, SSH_AUTH_SOCK from the host is not directly mountable into Docker. Docker Desktop uses /run/host-services/ssh-auth.sock; Colima requires forwardAgent: true and a VM-side socket path from colima ssh -- printenv SSH_AUTH_SOCK.
  • Claude config is split across ~/.claude/ and ~/.claude.json, and the config directory must be writable inside the container.
  • Claude OAuth creds on macOS live in Keychain, not just on disk.
  • gh tokens on macOS may also live in Keychain; gh auth token is the reliable extraction path.
  • Colima often defaults to 2GB RAM, which is too small for heavier agent workflows. 4GB+ is the practical floor.
  • Global npm installs as yolo need a user-writable prefix such as /home/yolo/.npm-global.
  • If a Docker build gets SIGKILL while equivalent runtime commands succeed, split heavy installers into a separate stage to reduce layer memory pressure.
  • Never chmod bind-mounted host sockets from inside the container. Fix access by matching the socket's group inside the container instead of mutating host permissions.
  • Setup defaults must come from global config only. Never seed a global-writing flow from merged project config, or repo-local settings will leak into every future run.
  • yolobox upgrade must not perform host-wide Docker cleanup. Pull the image you own; do not prune unrelated user images or caches as a side effect.
  • Version comparisons must be semantic, not lexical. Also stamp source-built binaries with a real version string, or update checks and support output become misleading.
  • install.sh runs under set -euo pipefail, so any best-effort network probe must explicitly tolerate failure. Otherwise the release lookup exits the script before the source-build fallback can run.
  • Help text for auto-forwarded env vars must be generated from autoPassthroughEnvVars. Hardcoded copies drift and create auth debugging noise.
  • Allocating a container TTY (-t) merges stdout and stderr at the PTY boundary. Only enable TTY for genuinely interactive commands, or host-side redirection and piping will behave incorrectly.
  • Codex trust is separate from execution mode. --ask-for-approval never plus --sandbox danger-full-access still shows the trust prompt for a new directory, so verify trusted-project startup separately when changing Codex launch flags.
  • Any sudo re-exec path in the entrypoint must preserve PATH (for example --preserve-env=PATH) or /opt/yolobox/bin wrappers get bypassed and AI CLIs lose pinned yolo flags.
  • Avoid parallel Git commands in this repo while another Git operation is active. We have repeatedly hit misleading .git/index.lock failures from overlapping status/checkout/rebase calls.
  • GitHub Pages deployments that use a custom Actions workflow should set the custom domain in the repository Pages settings. A checked-in CNAME file is ignored in that flow and only adds confusion.
  • For the VitePress docs site, stop the live dev container before running npm run docs:build. The dev server and build both write docs/.vitepress/dist, and the shared bind mount causes flaky build conflicts if both are active.
  • Social-card support is not just og:image. Ship a real robots.txt, generate a sitemap, and include explicit og:image:* plus twitter:image:alt metadata so crawlers and card parsers have stable image hints.
  • For VitePress SEO, do not hardcode canonical URLs or og: / twitter: titles in global head. Generate them per page from pageData, or every doc page will look like the homepage to crawlers.
  • Docker file bind mounts targeting a path inside an already bind-mounted project tree degrade into directories. Project file filtering must use a staged readonly project view rather than nested file mounts.
  • When yolobox itself runs inside another yolobox, temp mount sources must live under an existing host-visible bind mount like the project path. Inner-container /tmp is not visible to the outer Docker daemon.
  • Brand and social assets must not depend on runtime font rendering for the ASCII wordmark. Generate committed image assets from deterministic shapes, or social-card rasterization can drop the text and the site logo can drift from the share image.
  • Rootless Podman named volumes need :U alongside :Z when using --userns=keep-id, or older subordinate-ID ownership on yolobox-home reappears in-container as uid/gid 999 and breaks /home/yolo.
  • If the entrypoint remaps yolo to the host project UID/GID, it must also re-own /output; otherwise --readonly-project leaves the writable output volume stuck at the image's original 1000:1000 ownership.