Aztec Sandbox Devcontainer Feature

.github/workflows/test.yaml

@@ -7,7 +7,7 @@ on:
     workflow_dispatch:
 
 jobs:
-    test-global:
+    test-noir-barretenberg:
         runs-on: ubuntu-latest
         continue-on-error: true
         steps:
@@ -17,4 +17,16 @@ jobs:
               run: npm install -g @devcontainers/cli
 
             - name: "Testing global scenarios"
-              run: devcontainer features test --global-scenarios-only .
+              run: devcontainer features test -f noir_barretenberg
+
+    test-aztec-sandbox:
+        runs-on: ubuntu-latest
+        continue-on-error: true
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: "Install latest devcontainer CLI"
+              run: npm install -g @devcontainers/cli
+
+            - name: "Testing aztec-sandbox feature"
+              run: devcontainer features test -f aztec-sandbox

.gitignore

@@ -0,0 +1 @@
+CLAUDE.md

src/aztec-sandbox/README.md

@@ -0,0 +1,82 @@
+# Aztec Sandbox (aztec-sandbox)
+
+Installs and automatically runs the Aztec Sandbox development environment with test accounts pre-configured.
+
+## Example Usage
+
+```json
+"features": {
+    "ghcr.io/aztecprotocol/devcontainer-feature/aztec-sandbox:1": {}
+}
+```
+
+## Options
+
+| Options Id | Description | Type | Default Value |
+|-----|-----|-----|-----|
+| autoStart | Automatically start the sandbox on container creation | boolean | true |
+| importTestAccounts | Import test accounts using aztec-wallet | boolean | true |
+
+## What This Feature Does
+
+This feature:
+1. Installs the Aztec CLI and related tools
+2. Sets up the Aztec Sandbox to run automatically on container startup (if autoStart is true)
+3. Configures the environment with HOME set to /workspaces for Aztec compatibility
+4. Provides the aztec command in your PATH
+
+## Usage
+
+After installation, the `aztec` command is available in your PATH:
+
+```bash
+# If autoStart is false, manually start the sandbox:
+aztec start --sandbox
+
+# Check the version
+aztec --version
+```
+
+## Sandbox Management
+
+When autoStart is enabled (default), the sandbox runs in the background automatically. Logs are written to `/workspaces/.aztec/aztec-sandbox.log`.
+
+To monitor the sandbox logs in real-time:
+```bash
+tail -f /workspaces/.aztec/aztec-sandbox.log
+```
+
+## Test Accounts
+
+When `importTestAccounts` is enabled (default), test accounts are automatically imported and ready to use. These accounts come pre-funded and are ideal for development and testing.
+
+## Customization
+
+To disable auto-start and manage the sandbox manually:
+```json
+"features": {
+    "ghcr.io/aztecprotocol/devcontainer-feature/aztec-sandbox:1": {
+        "autoStart": false
+    }
+}
+```
+
+## Dependencies
+
+This feature automatically includes:
+- **Docker-in-Docker** (`ghcr.io/devcontainers/features/docker-in-docker:2`): Provides Docker daemon access required by the Aztec Sandbox
+
+## Notes
+
+- Node.js v20+ is required (v22 will be installed automatically if needed)
+- Port 8080 is used by the sandbox for the JSON-RPC endpoint
+- The Aztec tools are installed using the official installation script from install.aztec.network
+- Binaries are installed to `/workspaces/.aztec/bin`
+- HOME is set to `/workspaces` to ensure compatibility with Aztec's containerized applications
+- The sandbox runs in a Docker container managed by the Docker-in-Docker feature
+
+## GitHub Codespaces Support
+
+This feature includes special support for GitHub Codespaces:
+- Automatically configures the PXE_URL environment variable for Codespaces port forwarding
+- Ensures port 8080 is properly forwarded for sandbox access

src/aztec-sandbox/devcontainer-feature.json

@@ -0,0 +1,22 @@
+{
+	"name": "Aztec Sandbox",
+	"id": "aztec-sandbox",
+	"version": "1.0.0",
+	"description": "A feature to install and run Aztec Sandbox with test accounts",
+	"options": {
+		"autoStart": {
+			"type": "boolean",
+			"default": true,
+			"description": "Automatically start the sandbox on container creation"
+		},
+		"importTestAccounts": {
+			"type": "boolean",
+			"default": true,
+			"description": "Import test accounts using aztec-wallet"
+		}
+	},
+	"dependsOn": {
+		"ghcr.io/devcontainers/features/docker-in-docker:2": {}
+	},
+	"postCreateCommand": "/usr/local/share/aztec-sandbox-start.sh"
+}

src/aztec-sandbox/install.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+set -e
+
+echo "Activating feature 'aztec-sandbox'"
+
+# Get options
+AUTO_START="${AUTOSTART:-true}"
+IMPORT_TEST_ACCOUNTS="${IMPORTTESTACCOUNTS:-true}"
+
+# Install dependencies
+echo "Installing system dependencies..."
+apt-get update && apt-get install -y \
+    curl \
+    jq \
+    git
+
+# Install Node.js v22 if not present or version is too old
+echo "Checking Node.js version..."
+if ! command -v node &> /dev/null || [ $(node -v | cut -d'.' -f1 | sed 's/v//') -lt 20 ]; then
+    echo "Installing Node.js v22..."
+    curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
+    apt-get install -y nodejs
+fi
+
+# Set HOME to /workspaces persistently for all users and shells
+echo "Setting HOME to /workspaces persistently..."
+
+# Add to profile for login shells
+cat > /etc/profile.d/01_set_home.sh << 'PROFILE_EOF'
+# Set HOME to /workspaces for Aztec compatibility
+export HOME="/workspaces"
+
+# Add Aztec binaries to PATH
+if [ -d "/workspaces/.aztec/bin" ]; then
+    export PATH="/workspaces/.aztec/bin:$PATH"
+fi
+PROFILE_EOF
+
+chmod +x /etc/profile.d/01_set_home.sh
+
+# Add to bashrc for non-login shells
+cat >> /etc/bash.bashrc << 'BASHRC_EOF'
+
+# Set HOME to /workspaces for Aztec compatibility
+export HOME="/workspaces"
+
+# Add Aztec binaries to PATH
+if [ -d "/workspaces/.aztec/bin" ]; then
+    export PATH="/workspaces/.aztec/bin:$PATH"
+fi
+BASHRC_EOF
+
+# Create Aztec installation script that runs with correct HOME
+echo "Creating Aztec installation script..."
+cat > /usr/local/share/install-aztec.sh << 'EOF'
+#!/usr/bin/env bash
+set -e
+
+echo "Installing Aztec tools..."
+
+# Set HOME to /workspaces and change to that directory
+export HOME="/workspaces"
+cd /workspaces
+
+# Install Aztec using the official installation script (non-interactive mode)
+echo "Running Aztec installation script..."
+NON_INTERACTIVE=1 bash -c "curl -s https://install.aztec.network | bash -s"
+
+# Create .bashrc if it doesn't exist and set up PXE_URL for Codespaces
+if [ ! -f ~/.bashrc ]; then
+    touch ~/.bashrc
+fi
+
+if [ -n "\$CODESPACE_NAME" ] && ! grep -q "PXE_URL" ~/.bashrc; then
+    echo "export PXE_URL=https://\$CODESPACE_NAME-8080.preview.\$GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN" >> ~/.bashrc
+fi
+
+echo "Aztec tools installation complete!"
+EOF
+
+chmod +x /usr/local/share/install-aztec.sh
+
+# Create startup script for postCreateCommand
+echo "Creating startup script..."
+cat > /usr/local/share/aztec-sandbox-start.sh << EOF
+#!/usr/bin/env bash
+set -e
+
+# Set HOME to /workspaces
+export HOME="/workspaces"
+cd /workspaces
+
+# Wait for Docker to be ready
+echo "Waiting for Docker to be ready..."
+for i in {1..30}; do
+    if docker info &> /dev/null; then
+        echo "Docker is ready!"
+        break
+    fi
+    if [ \$i -eq 30 ]; then
+        echo "Timeout waiting for Docker to start. Docker may not be available."
+        echo "You can manually install Aztec later by running: /usr/local/share/install-aztec.sh"
+        exit 0
+    fi
+    echo "Docker not ready yet, waiting... (\$i/30)"
+    sleep 2
+done
+
+# Add Aztec to PATH for this session
+export PATH="/workspaces/.aztec/bin:\$PATH"
+
+# Install Aztec tools if not already installed
+if ! command -v aztec &> /dev/null; then
+    echo "Aztec tools not found. Installing..."
+    /usr/local/share/install-aztec.sh
+    # Re-export PATH after installation
+    export PATH="/workspaces/.aztec/bin:\$PATH"
+fi
+
+# Start the sandbox automatically if enabled
+if [ "${AUTO_START}" = "true" ]; then
+    echo "Starting Aztec Sandbox in background..."
+    mkdir -p /workspaces/.aztec
+    nohup /workspaces/.aztec/bin/aztec start --sandbox > /workspaces/.aztec/aztec-sandbox.log 2>&1 &
+    echo \$! > /workspaces/.aztec/aztec-sandbox.pid
+    echo "Aztec Sandbox started in background!"
+    echo "Logs: /workspaces/.aztec/aztec-sandbox.log"
+    echo "PID: \$(cat /workspaces/.aztec/aztec-sandbox.pid)"
+else
+    echo "Aztec setup complete!"
+    echo "The 'aztec' command is now available in your PATH."
+    echo "Run 'aztec start --sandbox' to start the sandbox manually."
+fi
+EOF
+
+chmod +x /usr/local/share/aztec-sandbox-start.sh
+
+echo "Aztec Sandbox feature installation complete!"
+echo "Aztec tools will be installed when the container starts."

test/aztec-sandbox/default.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+# This test file will be executed against an auto-generated devcontainer.json that
+# includes the 'aztec-sandbox' Feature with no options.
+#
+# For more information, see: https://github.com/devcontainers/cli/blob/main/docs/features/test.md
+#
+# Eg:
+# {
+#    "image": "<..some-base-image...>",
+#    "features": {
+#      "aztec-sandbox": {}
+#    },
+#    "remoteUser": "root"
+# }
+#
+# Thus, the value of all options will fall back to the default value in the
+# Feature's 'devcontainer-feature.json'.
+
+set -e
+
+# Optional: Import test library bundled with the devcontainer CLI
+source dev-container-features-test-lib
+
+# Feature-specific tests
+# The 'check' command comes from the dev-container-features-test-lib.
+
+# Check that installation and startup scripts exist
+check "install-script-exists" bash -c "test -x /usr/local/share/install-aztec.sh"
+check "startup-script-exists" bash -c "test -x /usr/local/share/aztec-sandbox-start.sh"
+
+# Check that HOME is set to /workspaces
+check "home-is-workspaces" bash -c "grep -q 'export HOME=\"/workspaces\"' /etc/profile.d/01_set_home.sh"
+
+# Check that PATH includes aztec binaries
+check "path-includes-aztec" bash -c "grep -q '/workspaces/.aztec/bin' /etc/profile.d/01_set_home.sh"
+
+# Check that Node.js is installed
+check "node-installed" bash -c "command -v node"
+
+# Report results
+# If any of the checks above exited with a non-zero exit code, the test will fail.
+reportResults

test/aztec-sandbox/scenarios.json

@@ -0,0 +1,17 @@
+{
+    "default": {
+        "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+        "features": {
+            "aztec-sandbox": {}
+        }
+    },
+    "with-options": {
+        "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+        "features": {
+            "aztec-sandbox": {
+                "autoStart": false,
+                "importTestAccounts": false
+            }
+        }
+    }
+}

test/aztec-sandbox/test.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# This is the primary test file that gets executed by default when running:
+# devcontainer features test -f aztec-sandbox
+#
+# It should test the basic functionality of the feature with default options.
+
+set -e
+
+# Import test library bundled with the devcontainer CLI
+source dev-container-features-test-lib
+
+# Feature-specific tests
+# Check that installation and startup scripts exist
+check "install-script-exists" bash -c "test -x /usr/local/share/install-aztec.sh"
+check "startup-script-exists" bash -c "test -x /usr/local/share/aztec-sandbox-start.sh"
+
+# Check that HOME is set to /workspaces
+check "home-is-workspaces" bash -c "grep -q 'export HOME=\"/workspaces\"' /etc/profile.d/01_set_home.sh"
+
+# Check that PATH includes aztec binaries
+check "path-includes-aztec" bash -c "grep -q '/workspaces/.aztec/bin' /etc/profile.d/01_set_home.sh"
+
+# Check that Node.js is installed
+check "node-installed" bash -c "command -v node"
+
+# Report results
+reportResults

test/aztec-sandbox/with-options.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+
+# This test file will be executed against the 'with-options' scenario in scenarios.json
+
+set -e
+
+# Import test library
+source dev-container-features-test-lib
+
+# Feature-specific tests
+# Check that installation and startup scripts exist
+check "install-script-exists" bash -c "test -x /usr/local/share/install-aztec.sh"
+check "startup-script-exists" bash -c "test -x /usr/local/share/aztec-sandbox-start.sh"
+
+# Check that HOME is set to /workspaces
+check "home-is-workspaces" bash -c "grep -q 'export HOME=\"/workspaces\"' /etc/profile.d/01_set_home.sh"
+
+# Check that PATH includes aztec binaries
+check "path-includes-aztec" bash -c "grep -q '/workspaces/.aztec/bin' /etc/profile.d/01_set_home.sh"
+
+# Since autoStart is false in this scenario, check that sandbox is NOT running
+# We can't check this directly as postCreateCommand hasn't run yet in tests
+
+reportResults