Architecture

How DevMagic is designed and why.

Design Principles

  • Zero friction — From "fresh OS" to "coding" in minutes
  • Consistency — Same environment on every machine
  • Modularity — Start minimal, add services as needed
  • Transparency — Open source, well-documented, no magic
  • Portability — Works on Windows, Linux, macOS identically
  • Separation of concerns — Container infrastructure vs personal preferences

Separation of Concerns

DevMagic deliberately separates container infrastructure from personal environment preferences:

DevMagic (Container)

  • • Base image & system packages (Dockerfile)
  • • Mounts & services (docker-compose.yml)
  • • Features, extensions & env (devcontainer.json)
  • • Host TZ/locale forwarding (localEnv)

Your Dotfiles (Personal)

  • • Homebrew, fzf, CLI tools
  • • Zsh plugins & shell config
  • • VS Code settings/keybindings
  • • Personal aliases & functions

Why this separation?

  • ✅ Your machine: Full personal setup with all your tools
  • ✅ Others using DevMagic: Working container without your config
  • ✅ Portable: Dotfiles work anywhere, not just containers
  • ✅ No lock-in: Works with VS Code, Neovim, Cursor, etc.

Installation Flow

curl -fsSL https://devmagic.run/install | bash
  → downloads the templates (templates/devcontainer/)
  → fills in your project folder name and writes
    devcontainer.json, docker-compose.yml and Dockerfile
    into .devcontainer/ — all shared values baked in, in sync
  → you open in VS Code and "Reopen in Container"

Container starts:
  → Docker Compose builds the image from the Dockerfile
  → devcontainer.json forwards host TZ/locale via localEnv
  → ~/.config/dotfiles is mounted from your host (optional)
  → optional postCreateCommand: oh-my-zsh, fzf, dotfiles shell init

Dotfiles Integration

DevMagic bind-mounts your dotfiles folder from the host into the container — no cloning, no syncing, always up to date.

Configuration

The compose file mounts ~/.config/dotfiles (host) at /home/node/.config/dotfiles (container):

# .devcontainer/docker-compose.yml (dev service)
volumes:
  - ..:/workspaces/<your-project>
  - ~/.config/dotfiles:/home/node/.config/dotfiles

Keep your dotfiles elsewhere? Adjust the mount in .devcontainer/docker-compose.yml. Optional extras (oh-my-zsh, fzf, shell init linking) come from the setup script.

  1. 1. Container starts

    Docker Compose bind-mounts ~/.config/dotfiles into the container

  2. 2. Optional setup

    Enable the commented postCreateCommand to install extras and link your dotfiles' shell init

  3. 3. Instant sync

    Host and container share the same folder — edits on either side appear immediately

Don't use dotfiles? Remove the mount line from .devcontainer/docker-compose.yml.

Technical Decisions

Homebrew over Conda

Better package availability for CLI tools (fzf, babashka, hugo), no licensing concerns.

Custom forks for security

Security-critical tools can be installed from your own forks for code review before updates.

VS Code configs via symlinks

Settings stored in dotfiles, symlinked to VS Code's User directory. Works in containers and native.

For the complete technical documentation, see docs/ARCHITECTURE.md on GitHub.