Configuration

Glovebox configuration lives in YAML profile files and supports environment variable passthrough.

Profile Files

Global Profile

Location: ~/.glovebox/profile.yaml

Defines your base development environment used across all projects.

version: 1
mods:
  - os/ubuntu
  - shells/zsh-ubuntu
  - editors/neovim
  - tools/mise
  - tools/homebrew
  - ai/claude-code
passthrough_env:
  - ANTHROPIC_API_KEY
  - GITHUB_TOKEN

Create with: glovebox init --base

Project Profile

Location: .glovebox/profile.yaml (in project directory)

Defines project-specific extensions to the base image.

version: 1
mods:
  - languages/nodejs
  - tools/tmux
passthrough_env:
  - DATABASE_URL

Create with: glovebox init

Profile Fields

Field	Description
version	Profile format version (currently 1)
mods	List of mod IDs to include
passthrough_env	Environment variables to pass from host

Environment Variable Passthrough

Glovebox can pass environment variables from your host to the container. This is essential for API keys, tokens, and other credentials.

Configuration

Add variables to passthrough_env in your profile:

passthrough_env:
  - ANTHROPIC_API_KEY
  - OPENAI_API_KEY
  - GITHUB_TOKEN
  - AWS_ACCESS_KEY_ID
  - AWS_SECRET_ACCESS_KEY

Behavior

• Variables from both global and project profiles are merged
• Only variables that are set in your host environment are passed through
• If a variable isn't set on the host, it's silently skipped

Visibility

When entering a container, Glovebox shows which variables are being passed:

  ┃ glovebox
  ┃
  ┃ Workspace   ~/projects/my-app
  ┃ Image       glovebox:my-app-abc1234
  ┃ Container   glovebox-my-app-abc1234 (new)
  ┃ Env         ANTHROPIC_API_KEY, GITHUB_TOKEN

Security Note

Passthrough variables are visible inside the container. Anyone (or any code) with access to the container can read them. This is intentional—they're needed for tools to work—but be aware of what you're exposing.

File Locations

Global (User) Files

Path	Purpose
~/.glovebox/profile.yaml	Global profile (base image definition)
~/.glovebox/Dockerfile	Generated base Dockerfile
~/.glovebox/mods/	Custom global mods

Project Files

Path	Purpose
.glovebox/profile.yaml	Project profile (extends base)
.glovebox/Dockerfile	Generated project Dockerfile
.glovebox/mods/	Custom project mods

Generated Dockerfiles

The Dockerfile in each location is generated by glovebox build. You can inspect it to understand what's being built, but don't edit it directly—changes will be overwritten.

To customize the build, modify your profile or create custom mods.

Image and Container Naming

Images

Type	Tag
Base	glovebox:base
Project	glovebox:<dirname>-<hash>

The hash is derived from the absolute path to ensure uniqueness across projects with the same name.

Containers

Type	Name
Base (rare)	glovebox-base
Project	glovebox-<dirname>-<hash>

Example Configurations

Minimal Base Profile

version: 1
mods:
  - os/ubuntu
  - shells/bash
  - editors/vim

Full-Featured Base Profile

version: 1
mods:
  - os/ubuntu
  - shells/zsh-ubuntu
  - editors/neovim
  - tools/mise
  - tools/homebrew
  - tools/tmux
  - ai/claude-code
passthrough_env:
  - ANTHROPIC_API_KEY
  - OPENAI_API_KEY
  - GITHUB_TOKEN
  - GH_TOKEN

Python Project Profile

version: 1
mods:
  - languages/python
passthrough_env:
  - VIRTUAL_ENV
  - PYTHONPATH

Node.js Project Profile

version: 1
mods:
  - languages/nodejs
passthrough_env:
  - NODE_ENV
  - NPM_TOKEN