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)

  • • SSH keys setup
  • • AI CLI tools
  • • Container-specific config
  • • Base dev environment

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 https://devmagic.run/install | bash
  → downloads .devcontainer/ to your project
  → you open in VS Code

Container starts:
  → postCreateCommand runs devcontainer-setup.sh
    → SSH keys setup
    → AI CLI tools installed
    → Dotfiles setup:
      → Clone repo if ~/prj/dotfiles doesn't exist
      → Run ~/prj/dotfiles/shell/install.sh
        → Your personal tools & config

Dotfiles Integration

DevMagic automatically clones and installs your dotfiles repository when the container is created.

Configuration

Set host environment variables (no devcontainer.json edits needed):

# Add to your ~/.bashrc or ~/.zshrc
export DEVMAGIC_DOTFILES_REPO="https://github.com/yourusername/dotfiles.git"
export DEVMAGIC_DOTFILES_BRANCH="main"  # optional, defaults to main

Host variables are passed via ${localEnv:VAR}. Defaults are in the setup script due to a spec limitation.

  1. 1. Container starts

    DevMagic checks if ~/prj/dotfiles exists

  2. 2. Clone if missing

    Automatically clones your dotfiles repository (shallow clone for speed)

  3. 3. Install

    Runs shell/install.sh to set up your personal environment

Disable dotfiles: export DEVMAGIC_DOTFILES_REPO=""

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.

Architecture - DevMagic