Reference

Known limitations and FAQ

What veil does not do yet, and answers to common questions.

What you will do: Check the known limitations, read the answers to common questions, and find out how to contribute or report a vulnerability.
Before you start: Nothing. You can read this page at any time.
What comes next: This is the last page. Follow planned work in the issues, or go back to the Introduction.

Known limitations

Linux only for now.
bubblewrap and user namespaces depend on kernel settings. When they are unavailable, veil refuses to start.
Interactive TUIs (full-screen terminal interfaces) and signal handling have had little testing.
veil doctor looks for bwrap on the PATH, while veil run requires /usr/bin/bwrap.
There is no IP rotation. The WARP exit address stays the same within a tunnel.
Not tested yet: the first start with an empty warp-data volume, and resolving the gateway's .local name on Linux hosts without mDNS.
veil has not had an external security review.

Open problems and planned work are tracked in the issues. Design decisions are recorded in docs/.

FAQ

Does it work on macOS?

Not natively yet. Planned A macOS Seatbelt backend that allows only the local proxy is planned; follow the issues. Today, veil run refuses to start on macOS. You can run the Linux build of veil and of your tool inside a Linux virtual machine or container. The end-to-end test used Docker Desktop on a Mac.

Does it rotate my IP?

No. The WARP exit address does not rotate. It stays the same within a tunnel, and accounts, prompts and code can still link your sessions.

Does Cloudflare see my IP?

Yes. Cloudflare sees your home IP and the traffic metadata. veil hides your IP from the tool's vendor, not from Cloudflare.

What happens if the gateway is down?

veil refuses to start. Before it runs the tool, it checks that it can reach the gateway, and it stops with gateway unreachable: refusing execution if it cannot. It never falls back to a direct connection.

Can I use Claude Code or Codex?

Only if the tool honors HTTPS_PROXY and its domains are in the gateway allowlist. OpenCode is the only tool tested end to end. Follow the steps in Using another tool. A tool that ignores HTTPS_PROXY fails instead of leaking.

Contributing and security

See CONTRIBUTING.md to build, test and propose changes.
Report vulnerabilities privately as described in SECURITY.md, never in a public issue.