Glovebox logo Glovebox
01.

Getting Started

Installation and first run

This guide covers installation options and getting your first Glovebox environment running.

Prerequisites

  • macOS (Apple Silicon): Apple Containers — preferred (brew install --cask container)
  • macOS / Linux: Docker — universal fallback
  • Go 1.25+ (only if building from source)

Installation

Homebrew (macOS/Linux)

brew tap joelhelbling/glovebox
brew install glovebox

This installs the glovebox command and a gb shorthand alias.

From Source

git clone https://github.com/joelhelbling/glovebox.git
cd glovebox
make build

Then add the bin directory to your PATH, or install system-wide:

make install  # installs to /usr/local/bin with gb symlink

First Run

A note on runtimes: On Apple Silicon Macs, Glovebox automatically uses Apple Containers, which runs each container in its own micro-VM for hardware-level isolation. On other platforms (or if Apple Containers isn't installed), Glovebox falls back to Docker. Either way, the commands below work the same.

1. Create Your Base Environment

Run the interactive setup to choose your OS, shell, editor, and tools:

glovebox init --base

You'll be prompted to select:

  • Base OS: Ubuntu, Fedora, or Alpine
  • Shell: bash, zsh, or fish
  • Editor: vim, neovim, helix, or emacs
  • Tools: mise (runtime manager), tmux, homebrew, etc.
  • AI assistants: claude-code, gemini-cli, opencode

Your selections are saved to ~/.glovebox/profile.yaml.

2. Build the Base Image

glovebox build --base

This generates a Dockerfile and builds your glovebox:base image. This step takes a few minutes the first time, but you only need to do it once (or when you change your base profile).

3. Run Glovebox

Navigate to any project directory and start a sandboxed session:

cd ~/projects/my-app
glovebox run

You're now inside a sandboxed container with your project mounted. Your shell, editor, and tools are all available.

4. Exit and Clean Up

When you're done, just exit the shell:

exit

Glovebox will detect any filesystem changes and ask if you want to commit them to the image. See Architecture for details on container persistence.

To remove all Glovebox containers and images:

glovebox clean --all

Next Steps