Skip to content

Add local development onboarding guide (gVisor + micro-VM/Lima) - #743

Open
Lucky Abolorunke (Oneimu) wants to merge 3 commits into
agent-substrate:mainfrom
Oneimu:setup-guide
Open

Add local development onboarding guide (gVisor + micro-VM/Lima)#743
Lucky Abolorunke (Oneimu) wants to merge 3 commits into
agent-substrate:mainfrom
Oneimu:setup-guide

Conversation

@Oneimu

Copy link
Copy Markdown

Why

There's currently no documentation for getting a working local development
environment from a fresh machine — in particular for the micro-VM runtime,
where the /dev/kvm requirement and asset staging make setup non-obvious, and
for macOS, where nested virtualization via Lima is undocumented. New
contributors have to reverse-engineer the hack/ scripts.

What

Adds docs/dev/onboarding.md, a single guide from zero to a working kind
cluster, based on notes from real onboarding runs:

  • Mental model & runtime comparison — a short WorkerPool / ActorTemplate /
    Actor / atenet-router primer and a gVisor vs micro-VM matrix, linking to
    docs/architecture.md and docs/glossary.md for depth.
  • Path A: gVisor on kind — zero-dependency happy path for any Linux/macOS
    machine with Docker.
  • Path B: micro-VM on kind — two host setups:
    • Linux with KVM (bare metal or a cloud VM with nested virtualization)
    • Apple Silicon macOS via Lima with --nested-virt (assets assembled inside
      the Lima guest, since assemble.sh requires a Linux host of the target arch)
  • Common actor lifecycle walkthroughkubectl-ate setup, create/resume,
    routing via the atenet-router Host header, and suspend/resume state
    persistence, identical for both runtimes.
  • Troubleshooting log — 7 symptom → root cause → fix entries actually hit
    during onboarding (docker/kvm permissions, PATH for kubectl-ate, staging
    before rustfs exists, M1 lacking FEAT_NV2, ...).
  • Known issues — two script rough edges surfaced in review, documented as
    bugs rather than intended UX:
    • the /dev/kvm probe requires host permission changes (should probe with a
      root container instead)
    • stage-to-rustfs.sh requires the aws CLI on the host (should run it via
      Docker); a containerized alias is provided as an interim workaround

Also links the guide from CONTRIBUTING.md under "Before you begin".

@Oneimu

Copy link
Copy Markdown
Author

/assign Benjamin Elder (@BenTheElder)

Comment thread docs/dev/onboarding.md Outdated
Comment thread docs/dev/onboarding.md Outdated
Comment thread CONTRIBUTING.md Outdated
Comment thread CONTRIBUTING.md Outdated
Comment thread docs/dev/onboarding.md Outdated
Comment thread docs/dev/onboarding.md Outdated
Comment thread docs/dev/onboarding.md Outdated
Comment thread docs/dev/onboarding.md Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants