Local install on Linux

60-second path

git clone https://github.com/pandastack-io/pandastack
cd pandastack
bash scripts/linux-local-e2e.sh
xdg-open http://localhost:3000

The script is idempotent. Re-running it skips work that is already done.

Step-by-step install

uname -sm
. /etc/os-release && echo "$PRETTY_NAME"
[ -e /dev/kvm ] && echo "kvm: ok" || echo "kvm: MISSING"

sudo usermod -aG kvm,docker "$USER"
newgrp kvm
newgrp docker

git clone https://github.com/pandastack-io/pandastack
cd pandastack

bash scripts/linux-local-e2e.sh

docker info >/dev/null && echo "docker ok"
go version           # 1.22+
node --version       # 20+
firecracker --version

docker exec pandastack-dev-postgres-1 pg_isready -U pandastack
curl -fsS http://localhost:8123/ping

systemctl status pandastack-agent-local-e2e.service --no-pager
curl -fsS http://localhost:7070/healthz

sudo journalctl -u pandastack-agent-local-e2e.service -f

curl -fsS http://localhost:8080/healthz
curl -fsS http://localhost:3000 >/dev/null && echo "dashboard ok"

TOKEN=pds_local_dev_token
TPL=$(curl -fsS -H "Authorization: Bearer $TOKEN" http://localhost:8080/v1/templates | jq -r '.[0].name')
ID=$(curl -fsS -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -X POST http://localhost:8080/v1/sandboxes \
  -d "{\"template\":\"$TPL\",\"ttl_seconds\":600}" | jq -r .id)
curl -fsS -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -X POST "http://localhost:8080/v1/sandboxes/$ID/exec" \
  -d '{"cmd":"echo hello"}' | jq -r .stdout

bash scripts/linux-local-e2e-down.sh

System requirements

What gets written where

Architecture (Linux)

┌────────────────────────── Linux host ──────────────────────────┐
│                                                                │
│  Browser ──► Dashboard (:3000) ──► API (:8080) ──► Agent (:7070)
│                                          │              │      │
│                                          ▼              ▼      │
│                                  Postgres (:5432)   Firecracker│
│                                  ClickHouse (:8123) microVMs   │
│                                  (Docker)           (KVM)      │
└────────────────────────────────────────────────────────────────┘

No Lima, no SSH hop, no host-side port forwarding gymnastics — everything talks to localhost.

Customization knobs

All overridable via environment variables before running the script:

To change ports, edit the script — defaults are 3000 (dashboard), 8080 (API), 7070 (agent), 5432 (Postgres), 8123 (ClickHouse), 9100/9101 (metrics).

Differences from production

Troubleshooting

/dev/kvm is missing on a cloud VM

You need nested virtualization enabled at the cloud provider:

• GCP: create the VM with --enable-nested-virtualization (requires --min-cpu-platform Haswell or later on x86, or any t2a Ampere image on arm).
• AWS: use bare-metal instance types (*.metal, e.g. c5.metal, m6g.metal).
• Azure: use Dasv5, Dadsv5, or any size that lists "Nested virtualization: Yes".
• Hetzner: dedicated/CCX (CPX shared do not expose KVM).

docker info says permission denied

Group changes do not apply to existing shells. Run:

newgrp docker

or log out and back in.

firecracker --version works but the agent fails to boot a sandbox

Check the agent log:

sudo journalctl -u pandastack-agent-local-e2e.service -n 200 --no-pager

Common causes: missing iptables/iproute2, SELinux/AppArmor blocking the agent (try sudo aa-status and disable the relevant profile), or nested-virt enabled but the cloud VM's kernel does not load kvm_intel/kvm_amd.

Port already in use

ss -ltnp 'sport = :8080'

Kill the offender or change the port in scripts/linux-local-e2e.sh.

Wipe and start over

bash scripts/linux-local-e2e-down.sh
sudo rm -rf .local-state/linux-local-e2e ./data /var/lib/pandastack
sudo rm -f /etc/systemd/system/pandastack-agent-local-e2e.service /etc/pandastack/local-e2e.env
sudo systemctl daemon-reload
bash scripts/linux-local-e2e.sh

FAQ

Q: Can I run this in WSL2? A: Not yet supported. WSL2 exposes /dev/kvm only on recent Windows 11 builds with nestedVirtualization=true, and even then, networking inside Firecracker is unreliable. Use a Linux VM or bare metal.

Q: Does this work on Raspberry Pi? A: An aarch64 Pi 5 with Ubuntu 24.04 may work but is not in CI. Pi 4 lacks the KVM extensions Firecracker requires.

Q: How do I expose the dashboard on my LAN? A: Edit the start_dashboard function and replace --hostname 127.0.0.1 with --hostname 0.0.0.0. Same for the API in build_and_start_api (change :8080 listen address). For anything beyond local LAN testing, put a real reverse proxy and TLS in front.

Q: How do I use real Supabase auth instead of the stub? A: See Self-hosted Supabase auth. Set PANDASTACK_AUTH_MODE=supabase and the matching env vars in /etc/pandastack/local-e2e.env, restart the unit, and rebuild the dashboard with the matching NEXT_PUBLIC_* variables.