How it works

The sandbox

On Linux, veil uses bubblewrap (bwrap), a small program that starts a process in its own namespaces. A namespace is a Linux kernel feature that gives a process a private view of one part of the system, such as the network, the file system, the process list or the host name. veil unshares all namespaces, so the tool gets an empty network with no way out, and it clears the environment variables.

veil mounts the system directories read-only, one workspace read-write at /workspace, and an empty or dedicated HOME.

The bridge

The sandbox sees only a unix socket, which is a file that two programs on the same machine use to talk to each other. A copy of veil inside the sandbox exposes this socket as 127.0.0.1:8118. It sets HTTP_PROXY, HTTPS_PROXY and NO_PROXY=127.0.0.1,localhost, so the tool sends its traffic there.

The gateway

The gateway is a Docker Compose stack on a machine in your local network. It allows only the domains that you list in an allowlist: a list of the only destinations that are allowed, where everything else is blocked. It sends the allowed traffic through a WARP WireGuard tunnel. WireGuard is the encrypted VPN protocol that WARP uses. DNS, the lookup that turns a name such as opencode.ai into an address, is resolved inside the tunnel, never by the client.

You set it up in Step 2.

Platforms

• Linux

  Supported

  With bubblewrap and unprivileged user namespaces. Tested end to end on arm64.

• macOS

  Planned

  A Seatbelt backend that allows only the local proxy. Track it in the issues.

• Windows

  Not supported

  See issue #3.

On other systems, veil run refuses to start. You can still run the Linux build of veil and of your tool inside a Linux virtual machine or container.