local: agent notes for bringing up a stack in a dev VM - #3293
Open
mdibaiee wants to merge 1 commit into
Open
Conversation
mdibaiee
force-pushed
the
mahdi/local-stack-agent-doc
branch
4 times, most recently
from
August 1, 2026 20:29
e67e132 to
e26ad53
Compare
mdibaiee
force-pushed
the
mahdi/local-stack-agent-doc
branch
from
August 1, 2026 22:56
e26ad53 to
b2eb1ab
Compare
local/README.md covers how the stack is wired. This is the operational companion: the order to do things in, and the failure modes that cost the most time because their symptom points somewhere other than their cause. Written from bringing a stack up from scratch in a Lima VM and running a connector in it. The expensive ones: - If vm:create-post fails -- mise resolves github:* tools through the GitHub API, whose unauthenticated quota is per source IP and can be exhausted by concurrent runs -- it aborts after the VM already exists, leaving no docker group membership and three downstream errors that each point somewhere other than the cause. - flow-supabase's TimeoutStartSec=300 may not cover a cold image pull, and pre-starting supabase by hand without the unit's env file silently creates a second, colliding project because project_id comes from FLOW_SUPABASE_PROJECT_ID. - local:stack leaves an already-running unit alone, so a unit can hold a stale PATH or endpoint from a previous env file indefinitely. Also have local:stack build flowctl, which local:stack-info already tells you to use but which nothing built.
mdibaiee
force-pushed
the
mahdi/local-stack-agent-doc
branch
from
August 1, 2026 23:35
b2eb1ab to
1e514ed
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description:
Adds
local/AGENTS.md: operational notes for bringing a local stack up in a dev VM — the order to do things in, and the failure modes whose symptom points somewhere other than their cause (half-bootstrapped VMs, supabase's start timeout, units holding stale env). Written from doing it end to end: VM up, stack up, tenant provisioned, task published. RootAGENTS.mdgains a pointer.It also recommends testing connectors through a
local:endpoint rather than an image, since the runtime execs the binary directly — no image build, noflow-connector-init, and no amd64 to match on an arm64 VM.Also has
local:stackdepend onbuild:flowctl, sincelocal:stack-infoprintsflowctlcommands to paste but nothing built it.Workflow steps:
mise run local:stackadditionally buildsflowctl. Otherwise documentation only.Documentation links affected:
None user-facing.
Notes for reviewers:
local/AGENTS.mdbecause rootCLAUDE.mdis already a symlink toAGENTS.md. Happy to fold it intolocal/README.mdinstead.