Maven Build with ccmvn

The ccmvn tool enables Maven to run in restricted sandbox environments where outbound HTTPS is blocked or DNS resolution is unavailable. It works by creating a local HTTP proxy that Maven uses to access Maven Central.

When to Use This Skill

• Running Maven builds (clean install, package, test, compile, etc.)
• Building Java projects that depend on Maven Central
• Working in sandboxed environments with network restrictions
• Needing to execute Maven with custom parameters and options

Prerequisites

Before using this skill, ensure:

1. Maven is installed: The system must have Maven 3.x installed
2. Node.js is available: Required for the proxy server (typically pre-installed in Claude Code)
3. Proxy configuration (for sandboxed Claude Code): The HTTPS_PROXY environment variable should be set if in a restricted sandbox

Basic Usage

Simple Build

npx ccmvn clean install

Other Common Commands

# Package the project
npx ccmvn package

# Run tests
npx ccmvn test

# Compile only
npx ccmvn compile

# Custom parameters
npx ccmvn clean install -DskipTests
npx ccmvn clean install -X  # Debug output

How ccmvn Works

ccmvn creates a three-layer proxy chain:

Maven → Local Proxy → Upstream Sandbox Proxy → Maven Central
       (HTTP)        (HTTP CONNECT)         (HTTP/2 over TLS)

Architecture Layers

1. Maven → Local Proxy (localhost:8080)

   • Plain HTTP communication
   • Maven configured via ~/.m2/settings.xml
   • No authentication required locally

2. Local Proxy → Upstream Proxy

   • HTTP CONNECT tunneling with JWT authentication
   • Upstream proxy performs DNS resolution for sandboxed environments

3. Local Proxy → Maven Central

   • HTTP/2 over TLS with ALPN negotiation
   • Secure connection to Maven Central repositories

Automatic Configuration

ccmvn automatically:

• Creates ~/.m2/settings.xml if it doesn’t exist
• Configures Maven to use the local proxy as a mirror for Maven Central
• Starts the proxy server before running Maven
• Cleans up the proxy server after Maven completes

Common Maven Commands

Advanced Options

Skip Tests During Build

npx ccmvn clean install -DskipTests

Run with Debug Output

npx ccmvn clean install -X

Specify Specific Goals

npx ccmvn clean compile test-compile

Use Custom Settings File

Maven will automatically use ~/.m2/settings.xml. To verify or modify proxy settings, check this file after running ccmvn.

Troubleshooting

Proxy Connection Issues

If you see proxy-related errors:

1. Ensure HTTPS_PROXY environment variable is correctly set (if in a sandboxed environment)
2. Check that the proxy server can reach Maven Central
3. Verify your proxy credentials are correct

Maven Not Found

If Maven is not installed:

# Install Maven (varies by system)
brew install maven  # macOS
apt-get install maven  # Ubuntu/Debian

Maven Central Timeout

If builds timeout accessing Maven Central:

1. Check your network connection
2. Try again – temporary network issues can cause timeouts
3. Use -X flag for debug output to see where it’s hanging

Settings.xml Issues

ccmvn automatically creates ~/.m2/settings.xml if missing. If you have a custom settings file:

1. Backup your current ~/.m2/settings.xml
2. Remove it and let ccmvn create a fresh one
3. Or manually add the proxy mirror configuration

Examples

Building a Spring Boot Application

npx ccmvn clean package -DskipTests

Running Unit Tests

npx ccmvn clean test

Full Build with All Checks

npx ccmvn clean install

Building Specific Module (in multi-module project)

npx ccmvn clean install -pl module-name

Environment Variables

HTTPS_PROXY (Sandboxed Environments Only)

Format: http://username:jwt_token@host:port

This is automatically used by ccmvn for sandboxed Claude Code environments. In local development, this is typically not needed.

Security

• Local proxy only: The proxy server is only accessible on localhost
• TLS validation: TLS certificates are validated for Maven Central
• End-to-end encryption: Connection through the proxy chain maintains encryption
• Token protection: JWT tokens are only used for authentication to the upstream proxy

Performance Tips

1. First build: Initial builds will download dependencies – this takes longer
2. Incremental builds: Subsequent builds with cached dependencies are much faster
3. Skip tests if not needed: Use -DskipTests to speed up builds during development
4. Use clean install sparingly: Only use clean when you have problems or need a fresh build

Resources

• ccmvn on npm
• ccmvn on GitHub
• Maven Documentation
• Maven Central Repository