Statically linked binaries are not intercepted

The preload backend only works with dynamically linked binaries. On Linux, use the eBPF backend (sudo silo setup-ebpf). On macOS, use CGO_ENABLED=1 or bind to $SILO_IP directly.

The eBPF backend requires cgroup v2 and kernel 5.8+. Run 'silo doctor' to check availability, then 'sudo silo setup-ebpf' to enable it. After setup, silo uses eBPF automatically.

Troubleshooting

Q: macOS: "running SIP-protected binary"

macOS strips DYLD_INSERT_LIBRARIES from binaries in /usr/bin, /bin, etc. Install a shell via Homebrew (brew install bash or brew install zsh) and silo will use it automatically.

Q: "password required" on every run

Silo needs sudo for adding loopback IP aliases and writing to /etc/hosts. Run 'sudo rm /etc/sudoers.d/silo' then 'silo doctor' to re-trigger passwordless setup.

Q: "not a git repository"

Silo derives the session IP from the git directory. Use --ip to set an address manually in non-git directories: silo run --ip 127.0.5.1 -- npm run dev

Q: Port still in use after stopping a server

IP aliases and /etc/hosts entries persist intentionally to avoid setup overhead. Run 'silo prune' to remove aliases with no listening ports, or 'silo prune --all' to remove everything.

Q: IP collision between worktrees

The FNV-1a hash has ~16.5 million possible addresses. Collisions are rare but possible. Override with: silo run --ip 127.0.99.1 -- npm run dev

Start with silo doctor. It checks your environment and flags issues.

macOS: "running SIP-protected binary"

macOS strips DYLD_INSERT_LIBRARIES from binaries in /usr/bin, /bin, etc. Silo tries to find a non-SIP alternative from your PATH automatically, but warns when it can't.

Fix: install a shell via Homebrew.

brew install bash
# or
brew install zsh

Silo will automatically pick the Homebrew version over the system one.

"password required" on every run

Silo needs sudo for two things: adding loopback IP aliases and writing to /etc/hosts. On first run, it installs passwordless sudo rules in /etc/sudoers.d/silo.

If this didn't happen, or the rules are stale:

# Remove and re-trigger setup
sudo rm /etc/sudoers.d/silo
silo doctor

"not a git repository"

Silo derives the session IP from the git directory. It won't work outside a git repo. If you need to run in a non-git directory, use --ip to set an address manually:

silo run --ip 127.0.5.1 -- npm run dev

Port still in use after stopping a server

The IP alias and /etc/hosts entry persist after the process exits. This is intentional. It avoids setup overhead on the next run. To clean up:

# Remove aliases with no listening ports
silo prune

# Remove everything
silo prune --all

IP collision between worktrees

The FNV-1a hash has ~16.5 million possible addresses in 127.0.0.0/8. Collisions are rare but possible. If two worktrees get the same IP, override one:

silo run --ip 127.0.99.1 -- npm run dev

silo run will also warn about IP collisions in /etc/hosts at startup.

Statically linked binaries

The preload backend (DYLD_INSERT_LIBRARIES / LD_PRELOAD) only works with dynamically linked binaries. Static Go binaries with CGO_ENABLED=0 won't be intercepted.

Fix (Linux): use the eBPF backend, which intercepts at the kernel level:

sudo silo setup-ebpf
silo ./my-static-binary

On macOS, there is no eBPF alternative. Use CGO_ENABLED=1 or bind to $SILO_IP directly in your code.

"already inside a silo session"

Silo warns when SILO_IP is already set in the environment. Nesting silo sessions is not supported. The inner session would override the outer one.

Linux: eBPF setup

The eBPF backend requires cgroup v2 and kernel 5.8+. Check with:

silo doctor --json | jq '.checks[] | select(.name | startswith("ebpf"))'

If eBPF is available but not set up:

sudo silo setup-ebpf

After setup, silo will use eBPF automatically. No LD_PRELOAD needed, works with static binaries.