GuideAugust 11, 20266 min read

ConfigSync + Devcontainers: Portable Dev Environments

Devcontainers give your team a reproducible environment. ConfigSync adds your personal touch on top. Together, they create the ideal development setup.

The Devcontainer Gap

VS Code devcontainers solve a real problem: every developer on the team gets the same tools, the same language versions, and the same system dependencies. No more "it works on my machine" caused by different Node versions or missing native libraries.

But devcontainers are deliberately impersonal. They define the team's environment, not yours. Inside a devcontainer, you lose your shell aliases, your Git identity, your SSH keys, and your editor customizations. The environment is reproducible but uncomfortable.

ConfigSync fills this gap. The devcontainer defines what the team needs. ConfigSync adds what you personally need on top.

Team Config vs. Personal Config

The key insight is separating team configuration from personal configuration:

LayerOwned ByDefined InExamples
Team environmentTeam/projectdevcontainer.jsonNode 20, PostgreSQL, Redis
Personal configIndividualConfigSyncShell aliases, Git identity, SSH keys

The devcontainer is checked into the repository and shared by the whole team. Your ConfigSync configuration is personal and encrypted. They complement each other perfectly.

Adding ConfigSync to devcontainer.json

Add ConfigSync to the postCreateCommand to pull your personal configs after the devcontainer is built:

.devcontainer/devcontainer.json
{ "name": "My Project", "image": "mcr.microsoft.com/devcontainers/typescript-node:20", "features": { "ghcr.io/devcontainers/features/docker-in-docker:2": {} }, "postCreateCommand": "npm install -g @inventivehq/configsync && configsync setup --token $CS_TOKEN && configsync pull --filter modules:git,modules:zsh,modules:ssh", "remoteEnv": { "CS_TOKEN": "${localEnv:CS_TOKEN}" } }

The remoteEnv section forwards your local CS_TOKENenvironment variable into the container. Set this once on your host machine and every devcontainer picks it up automatically.

Note: The postCreateCommand runs only once when the container is first created. If you rebuild the container, it runs again and pulls fresh configs.

What to Pull in a Devcontainer

In a devcontainer context, you typically want a focused subset of your environment:

Recommended modules for devcontainers
# Essential: Git identity and SSH access configsync pull --filter modules:git,modules:ssh # Comfortable: add shell customizations configsync pull --filter modules:git,modules:ssh,modules:zsh # Full: include editor settings (if not using VS Code settings sync) configsync pull --filter modules:git,modules:ssh,modules:zsh,modules:vscode

Skip modules that the devcontainer already handles. If the devcontainer installs project-specific tools, you do not need ConfigSync to manage those. Focus on personal configs that make the container feel like home.

Using Lifecycle Scripts

For more complex setups, use a dedicated script instead of cramming everything into postCreateCommand:

.devcontainer/setup.sh
#!/bin/bash set -e # Install ConfigSync npm install -g @inventivehq/configsync # Pull personal configs if [ -n "$CS_TOKEN" ]; then configsync setup --token "$CS_TOKEN" configsync pull --filter modules:git,modules:zsh,modules:ssh echo "Personal configs loaded successfully" else echo "No CS_TOKEN found, skipping personal config sync" fi
.devcontainer/devcontainer.json
{ "postCreateCommand": "bash .devcontainer/setup.sh" }

The script handles the case where a team member does not use ConfigSync. They still get the full devcontainer environment; they just miss the personal customizations. No one is forced to adopt ConfigSync to contribute to the project.

The Best of Both Worlds

Devcontainers plus ConfigSync gives you reproducibility and personalization. The team gets consistent environments. Each developer gets their own shell, identity, and preferences. When you switch projects, the devcontainer changes but your personal layer stays the same. It is the development environment you always wanted.

Ready to try ConfigSync?

Sync your entire dev environment across machines in minutes. Free forever for up to 3 devices.