DEV Community

Quinn Zhu
Quinn Zhu

Posted on

Record a Green Local Boot Before Agent Work Starts

#beginners #ai #git #programming

You must record one green local boot first.
Keep the agent closed until that boot exists.

Your first hour on a new repo is reproduction.
Code generation waits until the app actually starts.

An agent that never booted the service will guess.
Those guesses turn into noisy diffs and broken PRs.
You then spend review time explaining startup failures.

The failure this drill blocks

Juniors often open an agent before anything runs locally.
The agent patches files while the app never started.
You cannot split product bugs from setup bugs.

That mix is expensive on your first day.
Reviewers then cannot reproduce the agent's claim.
You also lack a clean baseline for a later revert.

What you pin before any agent session

Pin four facts before the first generated edit.
Write them in files the agent does not own.

  1. Copy the exact boot command from current docs.
  2. Name env files, and never copy secret values.
  3. Record the port and health path you expect.
  4. Save a timestamped log from one successful boot.

Do not pin passwords, tokens, or production hosts.
Pin commands, file names, and local health checks only.

Step 1: Freeze git state on a clean clone

Start from the default branch with a fast-forward pull.
Record HEAD and status before any tool edits files.

mkdir -p .agent/boot
git switch main
git pull --ff-only
git rev-parse HEAD > .agent/boot/head.sha
git status --short > .agent/boot/git-status.before.txt
Enter fullscreen mode Exit fullscreen mode

Keep .agent/boot/ out of the product commit when needed.
Add that path to a personal ignore file if policy requires it.

echo '.agent/' >> .git/info/exclude
Enter fullscreen mode Exit fullscreen mode

Step 2: Copy the documented boot command

Do not invent a start command from memory or chat.
Copy it from README, Makefile, or package scripts.

# Label: example only. Replace with your repo command.
printf '%s\n' 'make dev' > .agent/boot/command.txt
printf '%s\n' 'local API via make dev' > .agent/boot/why.txt
Enter fullscreen mode Exit fullscreen mode

If docs list several commands, pick one local service.
Write that choice in the one-line why.txt note.

Search the repo for the same command before you trust it.

grep -nR --include='Makefile' --include='README*' --include='package.json' \
  -e 'make dev' -e '"dev"' -e 'compose up' . | head
Enter fullscreen mode Exit fullscreen mode

A command that appears in two docs is safer than folklore.
A command that appears nowhere is not ready for an agent.

Step 3: Name env files without dumping secrets

List templates and local env filenames only.
Never redirect live secret values into the boot folder.

ls -1 .env* env.example .env.sample 2>/dev/null \
  > .agent/boot/env-files.txt || true
Enter fullscreen mode Exit fullscreen mode

Print required key names from the example file.
Skip values so the snapshot stays safe to share.

# Label: example. Point this at your example env file.
awk -F= '/^[A-Za-z_][A-Za-z0-9_]*=/ {print $1}' .env.example \
  > .agent/boot/env-keys.txt
Enter fullscreen mode Exit fullscreen mode

Confirm each named key exists in your private local file.
Missing keys are a hand-debug job, not an agent job.

# Label: example. Do not commit the private env file.
cut -d= -f1 .env | grep -v '^#' | sort > /tmp/local-env-keys.txt
sort .agent/boot/env-keys.txt > /tmp/required-env-keys.txt
comm -23 /tmp/required-env-keys.txt /tmp/local-env-keys.txt
Enter fullscreen mode Exit fullscreen mode

Any line from comm means you stop here.
Fill the local env yourself, then rerun the key check.

Step 4: Run boot with a hard timeout

Use a timeout so a hang cannot consume the whole hour.
Capture stdout, stderr, and the numeric exit code.

STAMP=$(date -u +%Y%m%dT%H%M%SZ)
CMD=$(cat .agent/boot/command.txt)
timeout 90s bash -lc "$CMD" \
  > ".agent/boot/boot.$STAMP.stdout.log" \
  2> ".agent/boot/boot.$STAMP.stderr.log"
echo $? > ".agent/boot/boot.$STAMP.exit"
printf '%s\n' "$STAMP" > .agent/boot/last.stamp
Enter fullscreen mode Exit fullscreen mode

Ninety seconds is a starting budget, not a law.
Increase it only when the README states a slower boot.

First compiles and image pulls often miss that window.
Run one manual warm boot before you start the clock.
Then pin the second boot as the golden log.

Step 5: Prove health, then snapshot the proof

Hit the local health route from the same docs.
Save the status code and a short body clip.

# Label: example. Replace port and path from README.
curl -sS -o .agent/boot/health.body \
  -w '%{http_code}\n' \
  http://127.0.0.1:3000/health \
  > .agent/boot/health.status
head -c 200 .agent/boot/health.body \
  > .agent/boot/health.body.clip
Enter fullscreen mode Exit fullscreen mode

A 200 is not enough by itself.
Confirm the body matches the documented JSON shape.

# Label: example. Change the key to match your docs.
grep -q '"status":"ok"' .agent/boot/health.body
echo $? > .agent/boot/health.shape.exit
Enter fullscreen mode Exit fullscreen mode

Hash the logs so later drift is visible.
Do not treat the hash as the only merge gate.

shasum -a 256 .agent/boot/boot.*.log \
  .agent/boot/health.status \
  .agent/boot/health.body.clip \
  > .agent/boot/boot.sha256
Enter fullscreen mode Exit fullscreen mode

Step 6: Stop the process you started

Leave the machine as you found it.
Do not gift the agent a dirty port or stale child.

# Label: example for a make-driven process group.
pkill -f 'make dev' || true
Enter fullscreen mode Exit fullscreen mode

Prefer the project's own stop target when it exists.
Record that stop command beside the boot command.

printf '%s\n' 'make stop' > .agent/boot/stop.txt
Enter fullscreen mode Exit fullscreen mode

Common boot failures you debug by hand

Read the stderr log before you blame application code.
Most first-hour failures are environment, not product logic.

  1. Missing .env keys show up as immediate crashes.
  2. Wrong language runtime versions break module imports.
  3. Occupied ports look like random connection refused errors.
  4. A stopped local database blocks every health request.
  5. Stale README commands start the wrong workspace package. 
# Port collision check. Replace 3000 with the documented port.
lsof -nP -iTCP:3000 -sTCP:LISTEN || true
Enter fullscreen mode Exit fullscreen mode

If the port is busy, identify the owner process first.
Do not kill random processes because an agent suggested it.

Decision table: may the agent start?

Use this table as a hard gate, not a vibe check.
Any Stop row means you stay in manual setup mode.

Signal Proceed Stop
Boot exit code is 0 Yes —
Health HTTP status is 200 Yes —
Health body matches docs Yes —
Required env keys are missing — Yes
Boot hit the timeout — Yes
Documented port is already in use — Yes
Secrets printed inside the boot log — Yes, scrub, retry
README command was not found in repo — Yes

If a Stop cell matches, you debug without the agent.
The model does not get a turn until boot is green.

After boot is green: one narrow agent pass

Give the agent the ticket and the boot file names.
Forbid edits under .agent/boot/ and any secret paths.

Tell it to keep the same boot command unchanged.
Tell it to fail if health no longer returns 200.

# Label: prompt template, not an executed script.
Ticket: <id>
Boot command file: .agent/boot/command.txt
Health: GET http://127.0.0.1:3000/health must stay 200
Do not edit .agent/boot/**
Do not edit .env, credentials, or deploy manifests
After your patch I will rerun the same boot command
Enter fullscreen mode Exit fullscreen mode

Re-run the same timeout command after the diff.
Compare health status before you compare full logs.

timeout 90s bash -lc "$(cat .agent/boot/command.txt)" \
  > /tmp/boot.after.stdout.log \
  2> /tmp/boot.after.stderr.log
echo $? > /tmp/boot.after.exit
curl -sS -o /tmp/health.after.body \
  -w '%{http_code}\n' \
  http://127.0.0.1:3000/health \
  > /tmp/health.after.status
diff -u .agent/boot/health.status /tmp/health.after.status
diff -u .agent/boot/boot.*.exit /tmp/boot.after.exit
Enter fullscreen mode Exit fullscreen mode

A changed health code blocks the pull request.
A new stack trace in stderr needs your own read.
You explain that delta before you request review.

If health fails, revert the agent branch first.
Do not stack extra prompts on a service that will not boot.

git switch main
git branch -D agent/ticket-id || true
Enter fullscreen mode Exit fullscreen mode

Where a free agent lane fits

Some teams lack spare paid seats on day one.
You still need a model for one narrow patch draft.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode offers free model access and a free server option.
You can run this boot-first drill there without a paid seat.
The product does not replace your health check or revert.

Use it only after the boot log is already green.
Paste the boot command and the health contract only.
Do not paste secret values into the prompt or chat.

If you want a free lane for this drill, that option exists.
Keep the first PR small enough that you can still revert it.

Limitations

This workflow assumes a bootable local application.
Monorepos with remote-only services will not boot cleanly.
You then pin a narrower contract, such as unit tests.

Log hashes drift when timestamps fill stdout lines.
Do not treat hash equality as the only merge gate.
Health status and exit code stay the primary gates.

Timeouts misfire on cold compiles and image pulls.
Warm the toolchain once before you pin the golden log.
Otherwise you will reject healthy but slow first boots.

Agents can still break migrations and seed scripts.
This method does not prove database shape or fixtures.
Add a seed check when your ticket touches storage.

Who should not use this

Skip this if you cannot run the service locally.
Skip this if policy forbids local secrets on your laptop.
Skip this if CI already owns a green compose healthcheck.

Staff on well-paved repos may already have this ritual.
Do not add a parallel folder that duplicates Makefile targets.
Prefer the team's script when it already snapshots boot.

Juniors on locked-down laptops should ask for a devcontainer.
Do not spend six hours on Docker instead of reading code.
The point is a baseline, not a perfect local factory.

Close

Your first agent PR needs a boot you can repeat.
Pin the command, the health code, and the log.
Then let the model touch a narrow slice of code.

If boot breaks after the diff, you stop immediately.
You revert before you request review from anyone.
That is the whole first-hour job on a new repo.

Top comments (0)