Liquescent Development DevContainer Templates

A collection of secure, polyglot development container templates with network isolation, comprehensive language support, and enterprise-grade secret management.

This repository contains Dev Container templates that follow the official Dev Container specification. Templates are located in the src/ directory and can be used to quickly set up development environments in any project.

📦 Repository Structure

├── src/                         # Dev Container templates (distributed to users)
│   └── liquescent-devcontainer/ # Our primary template
├── image-sources/               # Dockerfiles for pre-built images (maintainers only)
│   └── liquescent-devcontainer/ # Source for building the template's image
└── .github/workflows/           # CI/CD for building and publishing images

🔧 Available Templates

liquescent-devcontainer

Our flagship development container template:

• Uses pre-built image from ghcr.io/liquescent-development/liquescent-devcontainer:latest
• Fast startup - no build time required
• Self-contained template in src/liquescent-devcontainer/
• Ready for distribution via OCI registry

🔒 Key Features

Security & Network Isolation

• Firewall-enforced network isolation using iptables and ipset
• Allowlisted domains only - blocks unauthorized network access
• Custom domain support via environment variables or project configuration
• SOCKS5 proxy support for controlled external access
• Non-root user execution with selective sudo permissions

Language & Tool Support

• Polyglot development - Go, Python, Rust, .NET, Node.js via Dev Container Features
• Modern shell environment - Zsh with Oh-My-Zsh and Oh-My-Posh theming
• Development tools - Git, GitHub CLI, FZF, Git Delta, direnv
• AI assistance - Claude Code CLI pre-installed
• Secret management - 1Password CLI with Connect Server and Service Account support

Developer Experience

• Instant startup - Pre-built image from GitHub Container Registry
• Persistent history - Shell history preserved across container rebuilds
• SSH agent forwarding - Seamless git operations and commit signing
• Automatic environment loading - direnv integration for .env files
• VS Code optimized - Pre-configured extensions and settings

🚀 Quick Start

Prerequisites

• Docker Desktop, OrbStack, Colima, or Rancher Desktop
• VS Code with Dev Containers extension
• Git

Option 1: Manual Copy (Simple)

1. Copy the template's .devcontainer folder from src/liquescent-devcontainer/.devcontainer/ to your project root

2. Configure your environment:

   cp .devcontainer/.env.example .devcontainer/.env
   # Edit .devcontainer/.env with your settings

3. Open in VS Code:

   code .

   Then use the command palette: Dev Containers: Reopen in Container

The container will build from the included Dockerfile on first use.

Option 2: Using Dev Container CLI (Recommended)

1. Install the Dev Container CLI (if not using VS Code):

   npm install -g @devcontainers/cli

2. Apply the template to your project:

   From this repository (for development/testing):

   devcontainer templates apply \
     --workspace-folder . \
     --template-id ./src/liquescent-devcontainer

   Or from the published template (when available):

   devcontainer templates apply \
     --workspace-folder . \
     --template-id ghcr.io/liquescent-development/templates/liquescent-devcontainer

3. Configure and customize as needed

4. Open in your preferred tool (VS Code, CLI, etc.)

⚙️ Configuration

Environment Variables

The devcontainer uses Docker Compose to automatically load environment variables from .devcontainer/.env.

Key configuration options in .devcontainer/.env:

# Timezone
TZ=America/Phoenix

# Custom allowed domains (comma-separated)
CUSTOM_ALLOWED_DOMAINS=api.mycompany.com,staging.myapp.io

# 1Password Configuration (optional)
OP_SERVICE_ACCOUNT_TOKEN=ops_...
# OR use Connect Server
OP_CONNECT_HOST=https://connect.mycompany.com
OP_CONNECT_TOKEN=...

# Git configuration mounting
MOUNT_HOST_GIT_CONFIG=true

See .env.example for all available options.

Network Access

By default, only these domains are accessible:

• GitHub (github.com, api.github.com, etc.)
• npm registry (registry.npmjs.org)
• Python Package Index (pypi.org, files.pythonhosted.org, pypi.python.org)
• VS Code Extension Marketplace (marketplace.visualstudio.com, *.gallery.vsassets.io, vscode.blob.core.windows.net)
• Anthropic API (api.anthropic.com, statsig.anthropic.com, sentry.io)
• 1Password (*.1password.com, *.1password.eu, *.1password.ca, *.1passwordservices.com)

Adding Custom Domains

Method 1: Environment Variable (personal/temporary)

# In .devcontainer/.env
CUSTOM_ALLOWED_DOMAINS=api.example.com,db.internal.net

Method 2: Project Configuration (team/permanent) Create an allowed-domains.txt file in .devcontainer/:

# In .devcontainer/allowed-domains.txt
api.example.com
staging.example.com
192.168.1.0/24

Secret Management

1Password Integration

The 1Password CLI is pre-installed but requires authentication configuration.

Option 1: Service Account (Recommended for DevContainers)

Service accounts provide secure, non-interactive authentication perfect for development containers.

# On your host machine:
# 1. Install 1Password CLI: https://developer.1password.com/docs/cli/get-started
# 2. Sign in: op signin
# 3. Create a service account:
op service-account create "devcontainer-$(basename $(pwd))" --expires-in 30d

# 4. Copy the token (starts with 'ops_') to .devcontainer/.env:
OP_SERVICE_ACCOUNT_TOKEN=ops_YOUR_TOKEN_HERE

# For vault-specific access (more secure):
op service-account create "my-dev" --expires-in 30d --vault Development:read_items

Option 2: Connect Server (For Teams/Enterprise)

# In .devcontainer/.env:
OP_CONNECT_HOST=https://connect.company.com
OP_CONNECT_TOKEN=your-connect-token

Usage in container:

# Inject environment variables from 1Password
op run --env-file=prod.env -- npm start

# Read specific secrets
export API_KEY=$(op read "op://vault/item/field")

# Use with git for secure commit signing
op plugin init git

🏗️ Architecture

Container Structure

• Base: Node.js 20 on Debian
• Languages: Installed via Dev Container Features (not in base image)
• User: Runs as node user with selective sudo
• Shell: Zsh with extensive plugin support
• Network: iptables rules applied at startup

File Mounts

• /workspace - Your project files
• /commandhistory - Persistent shell history
• /home/node/.claude - Claude configuration (if using Claude Code)
• /ssh-agent - SSH agent socket forwarding

Security Model

1. Network traffic blocked by default
2. DNS resolution allowed for domain lookup
3. Specific IPs/domains added to allowlist
4. All outbound traffic must pass through firewall rules
5. Container runs as non-root user

📚 Advanced Usage

Using SOCKS5 Proxy

The container supports configurable SOCKS5 proxy access for routing traffic through VPNs or corporate proxies.

Configuration in .devcontainer/.env:

SOCKS5_ENABLED=true                    # Enable/disable proxy access
SOCKS5_HOST=host.docker.internal       # Proxy host (hostname or IP)
SOCKS5_PORT=1080                        # Proxy port

Using the proxy in the container:

# Configure git
git config --global http.proxy socks5://${SOCKS5_HOST}:${SOCKS5_PORT}

# Use with curl
curl --socks5 ${SOCKS5_HOST}:${SOCKS5_PORT} https://example.com

# Use with Python
export HTTP_PROXY=socks5://${SOCKS5_HOST}:${SOCKS5_PORT}
export HTTPS_PROXY=socks5://${SOCKS5_HOST}:${SOCKS5_PORT}

Common proxy scenarios:

• Local SSH tunnel: ssh -D 1080 user@jumphost then use default settings
• Corporate proxy: Set SOCKS5_HOST to your proxy server
• VPN client: Many VPN clients provide SOCKS5 on localhost:1080
• Disable proxy: Set SOCKS5_ENABLED=false if not needed

Debugging Network Issues

# Enable firewall logging to see blocked connections
echo "FIREWALL_LOG_ENABLED=true" >> .devcontainer/.env
# Restart container, then view logs
sudo dmesg -w | grep 'FW-BLOCKED'

# Check firewall rules
sudo iptables -L -v -n

# View allowed domains
sudo ipset list allowed-domains

# Test connectivity
curl -v https://example.com

For detailed troubleshooting, see the Firewall Logging Guide.

Performance Tuning

The container is configured with:

• 2 CPU cores minimum
• 4GB RAM minimum
• 32GB storage recommended
• Node.js max memory: 4GB

Adjust in devcontainer.json under hostRequirements if needed.

🔧 Customization

Building Your Own Image

If you need to customize the base image:

cd docker-image
./build.sh

See docker-image/README.md for detailed build instructions.

Adding VS Code Extensions

Edit devcontainer.json:

"customizations": {
  "vscode": {
    "extensions": [
      "your.extension-id"
    ]
  }
}

📖 Documentation

• Firewall Logging Guide - Debug network connectivity issues
• Docker Image Build Guide
• Environment Variables Reference
• Dev Container Specification

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Developed by Liquescent Development