Skip to content

First Sandbox

Install Vibepit, launch an isolated sandbox for a project, and verify that network filtering is working.

Prerequisites

  • Linux or macOS (amd64 or arm64)
  • Docker or Podman installed and running
  • Your user can access the container runtime socket (e.g., you can run docker ps or podman ps without errors)

1. Install Vibepit

Download the latest release and place the binary on your PATH:

curl -fsSL https://vibepit.dev/download.sh | bash
mv vibepit "$HOME/.local/bin/"

Confirm the installation:

vibepit --help

2. Move into a project directory

Vibepit mounts your current working directory into the sandbox so the code is available inside the container at the same path.

cd ~/projects/my-app

Tip

Vibepit refuses to run if your working directory is your home directory. Always cd into a specific project first.

3. Launch the sandbox

Run vibepit with no arguments. The default command is run.

vibepit

First-run experience

On the first run inside a project, Vibepit presents a preset selector. Presets define which network destinations (domains and ports) the sandbox is allowed to reach.

  • Vibepit auto-detects language presets from project files. For example, a go.mod file triggers the pkg-go preset.
  • The default preset is always pre-selected. It includes common destinations such as package registries and GitHub.

Select the presets you need and press Enter. The choices are saved to .vibepit/network.yaml in the project directory.

For details on creating and managing presets, see Configure Network Presets.

4. What happens under the hood

When the sandbox starts, Vibepit:

  1. Creates an isolated Docker network with no external connectivity.
  2. Starts a proxy container on that network. The proxy runs a DNS server and an HTTP/HTTPS filtering proxy. Only allowlisted domains are resolvable and reachable.
  3. Starts a sandbox container on the same network. The container runs with a read-only root filesystem, dropped capabilities, and no-new-privileges. Your project directory is bind-mounted in, and persistent home/linuxbrew volumes preserve shell state and installed tools between sessions.

For a deeper look, see Architecture.

5. Work inside the sandbox

Once the sandbox shell appears, you are inside the sandbox container. A few things to note:

  • Your project is mounted at its original absolute path (e.g., /home/you/Code/myproject on the host is available at the same path inside the sandbox). This keeps file references and tooling consistent.
  • Your home directory inside the sandbox is /home/code, not your host home directory. This is a persistent volume that survives across sessions.
  • Only allowlisted domains are reachable. Requests to any other destination are blocked by the proxy.
  • You can install additional language runtimes and tools with Homebrew. See Install Development Tools for details.

For the full list of environment variables, mounts, and hardening settings, see the Sandbox Environment reference.

6. Open the monitor

The monitor provides a live view of proxy logs and lets you manage allowlist entries interactively. From a separate terminal on the host:

vibepit monitor

For details on using the monitor and managing the allowlist at runtime, see Monitor and Allowlist.

7. Allow extra domains at startup

If you know ahead of time that you need access to additional domains, pass them on the command line:

vibepit -a example.com:443

You can also enable an entire preset:

vibepit -p vcs-github

Both flags can be repeated. See the CLI Reference for the full list of flags.

8. Check active sessions

From a separate terminal on the host, list running sessions:

vibepit sessions

This shows each active session along with its project directory and network details.

9. Open additional terminals

While a session is running, you can open additional shells inside the same sandbox. Run vibepit again from the same project directory in a separate terminal:

vibepit

Vibepit detects the existing session and opens a new shell inside it instead of creating a new one.

Important: Session lifecycle

The session is tied to the first vibepit process. When that process exits normally, Vibepit cleans up the session — containers and the network are removed — even if other shells are still open. Additional shells opened with vibepit are exec sessions inside the existing container and do not keep the session alive on their own.

Alternative: daemon mode

Instead of attaching your terminal directly, you can run the sandbox in the background. This is useful when you want sessions that persist across disconnects or when running AI agents that connect via SSH.

Start the session

vibepit up

This starts the sandbox and proxy containers in the background and prints the SSH address when ready.

Connect to the sandbox

vibepit connect

Each connection opens a shell session inside the sandbox. If you disconnect (close the terminal, network drop), the shell session continues running. When you reconnect, the server presents a selector where you can reattach to the previous session or start a new one.

You can also run a single command without an interactive shell:

vibepit exec ls -la

Check status

vibepit status

Shows container status, uptime, and published ports (control API and SSH).

Stop the session

vibepit down

This stops and removes all containers and cleans up credentials. Unlike run mode, the session keeps running until you explicitly stop it.

For full details on all commands and flags, see the CLI Reference.