An isolated Lima dev VM on macOS, with all SSH auth and git signing routed through a YubiKey. The host holds the FIDO2 credentials; the VM never sees a private key. Lima reverse-forwards a user-space ssh-agent socket into the VM, scoped to github.com only.

• Ubuntu 26.04 LTS ARM64 in Lima, hardened: no host filesystem mounts, reversed agent socket forward, USB only as needed.
• Two ed25519-sk resident credentials on the YubiKey:
  • auth key (PIN + touch per use) for git push/pull to GitHub.
  • sign key (touch per use) for git commit -S / git tag -s.
• Inside the VM: Docker, Rust (rustup), fish as default shell, git pre-configured to sign with the forwarded SK key, ~/.ssh/config pinned to github.com only.

• macOS on Apple Silicon.
• Homebrew + Lima: brew install lima.
• ssh-askpass on a known path: brew install theseal/ssh-askpass/ssh-askpass.
• A YubiKey with FIDO2 enabled and a PIN already set (ykman fido access change-pin).
• Fish shell on the host (the post-bootstrap instructions assume fish/conf.d).
• The following env exported in your fish config (e.g. ~/.config/fish/conf.d/ssh-askpass.fish):

  set -gx SSH_AUTH_SOCK $HOME/.ssh/agent.sock
  set -gx SSH_ASKPASS /opt/homebrew/bin/ssh-askpass
  set -gx SSH_ASKPASS_REQUIRE force

No package manager. Clone the repo and either add it to PATH or symlink the dispatcher:

git clone <repo-url> ~/src/alpaca
ln -s ~/src/alpaca/alpaca ~/bin/alpaca   # or fish_add_path the repo dir

alpaca resolves its own symlinks, so it finds the sibling scripts regardless of where you symlink it from.

alpaca prerequisites install  # one-time: brew-install lima, ssh-askpass, ykman, libfido2
alpaca enroll                 # one-time: create the two SK credentials on the YubiKey
alpaca bootstrap              # build the VM and load the keys into a fresh user-space agent
alpaca doctor                 # verify everything end-to-end

After bootstrap, paste the printed pubkeys into https://github.com/settings/ssh/new (one as Authentication, one as Signing).

vm-setup.sh is intentionally not exposed via alpaca — it runs inside the VM, invoked by bootstrap.sh.

Each underlying script in cmd/ also takes --help directly (e.g. cmd/bootstrap.sh --help).

        ┌──────────────┐
        │   YubiKey    │  ed25519-sk credentials
        │  auth │ sign │  never leave the device
        └──────┬───────┘
               │ libfido2
               │ PIN (auth only) + touch (always)
        ───────┼──────── trust boundary ────────
               │
        ┌──────┴───────────────────────┐
        │ macOS host                   │
        │  ssh-askpass → ssh-agent     │
        │             ~/.ssh/agent.sock│
        └──────────────┬───────────────┘
                       │ reverse-forwarded unix socket
                       │ (Lima exposes the agent to the VM —
                       │  signatures only, no key material)
        ┌──────────────┴───────────────┐
        │ Lima VM                      │
        │  • no host filesystem mounts │
        │  • ssh pinned to github.com  │
        │    (~/.ssh/config in VM)     │
        └──────────────┬───────────────┘
                       │ git over ssh
                       ▼
                  github.com

What the VM isolation gives you:

• No host filesystem access. The VM cannot read ~, /etc, or anything else on the Mac — there are no shared mounts.
• Keys never enter the VM. Lima reverse-forwards the host's user-space ssh-agent as a Unix socket; the VM can request signatures, but the credentials live on the YubiKey.
• SSH scoped to GitHub. ~/.ssh/config in the VM pins the forwarded agent to github.com only — outbound SSH to anywhere else won't draw on the SK keys.
• Hardware-attested signatures. The auth key has verify-required set, so every signature requires a PIN via host ssh-askpass plus a YubiKey touch. The sign key requires touch only.

Residual risks:

• Kernel-level VM escape. Lima/QEMU isn't a Type-1 hypervisor — the VM shares the host kernel, so a kernel exploit can cross the boundary.
• Host compromise reaches the VM. limactl shell and the VM's Lima-managed SSH run with your macOS user's privileges; any process running as you can drop into the VM.
• Signing oracle while the YubiKey is plugged in. A compromised process in the VM can ask the forwarded agent to sign on its behalf. The auth key's PIN+touch requirement blocks silent abuse, but the sign key only requires touch — don't approve touch prompts you didn't trigger.

• alpaca bootstrap is destructive — it deletes the named VM. If you have state inside the VM you care about, copy it out first.
• Apple Silicon only (isolated-dev.yaml pins arch: aarch64).
• Host-side post-install instructions assume fish. If you use a different shell, translate the set -gx lines.
• ykman is recommended (for doctor to inspect FIDO2 PIN status) but not required for the bootstrap path itself — OpenSSH talks to the YubiKey via libfido2 directly.