Requirements for Running OpenMAIC on a Slow Network or in China

You can build and deploy OpenMAIC behind limited bandwidth or inside China by passing the ALPINE_MIRROR and NPM_REGISTRY Docker build-args to redirect Alpine Linux and npm package downloads to fast, local mirrors.

OpenMAIC is an open-source agent framework developed by THU-MAIC that relies on containerized deployment. When building from source in regions with restricted external connectivity or slow international links, you must configure alternative package sources to avoid timeouts and throttling during the image build process.

Understanding Build-Time Network Dependencies

OpenMAIC’s container image is constructed from an Alpine Linux base (node:22-alpine) and installs dependencies via apk (Alpine Package Keeper) and npm. By default, these tools reach out to upstream servers hosted outside mainland China, which the Great Firewall may throttle or block entirely.

Build-Time vs Runtime Fetching

The mirror configuration only speeds up build-time fetching. It replaces the default Alpine CDN (dl-cdn.alpinelinux.org) and the global npm registry with domestic alternatives. However, this does not affect runtime pulls from Docker Hub (such as fetching the node:22-alpine base image). For runtime image pulls, you must configure a separate Docker daemon registry mirror.

Configuring China-Accessible Mirrors

The repository’s Dockerfile accepts two optional build arguments that override the default package repositories. According to the source code in README.md (lines 15-34), these arguments are consumed during the apk add and npm install steps.

Alpine Linux Mirror (ALPINE_MIRROR)

Set the ALPINE_MIRROR build-arg to a Chinese mirror host such as mirrors.tuna.tsinghua.edu.cn. The Dockerfile uses this value to configure apk before installing system dependencies, ensuring packages download from the local mirror instead of the default Alpine CDN.

npm Registry Mirror (NPM_REGISTRY)

Set the NPM_REGISTRY build-arg to a public npm mirror such as https://registry.npmmirror.com. The Dockerfile executes npm config set registry $NPM_REGISTRY prior to npm install, routing all Node.js package requests through the fast domestic mirror.

Step-by-Step Build Instructions

Both arguments are optional; omitting them uses the standard upstream mirrors. You can inject these values via the command line whether you use Docker Compose or a direct docker build invocation.

Docker Compose with Mirror Arguments

Pass the mirror URLs as environment variables when invoking docker compose. The Compose file automatically promotes these to build-args during the image build phase.

ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn \
NPM_REGISTRY=https://registry.npmmirror.com \
docker compose up --build

This command builds the OpenMAIC image using Tsinghua University’s Alpine mirror and Alibaba’s npmmirror registry, then starts the containers.

Direct Docker Build

For a one-off image creation without Compose, pass the arguments explicitly using the --build-arg flag:

docker build \
  --build-arg ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn \
  --build-arg NPM_REGISTRY=https://registry.npmmirror.com \
  -t openmaic:local .

This creates a local image tagged openmaic:local with all dependencies fetched through the specified mirrors.

Environment Configuration

Before building, copy the environment template and add your LLM API keys. The mirror settings should remain on the command line, not in the .env file.

cp .env.example .env.local

# Edit .env.local to add your API keys

docker compose up --build

The .env.example file (located in the repository root) serves as a template for required runtime variables such as LLM API credentials, while build-time mirror configuration stays separate.

Security Considerations for Build Arguments

Never embed usernames, passwords, or tokens inside the ALPINE_MIRROR or NPM_REGISTRY arguments. Docker records build-args in the final image metadata, which could leak credentials if the image is pushed to a registry. The mirrors referenced in the OpenMAIC documentation are public and require no authentication.

Summary

• Use build-args for mirrors: Pass ALPINE_MIRROR and NPM_REGISTRY to redirect apk and npm to China-accessible servers.
• ** Affects build only**: These settings speed up package downloads during docker build, but do not configure runtime Docker Hub pulls.
• No secrets in args: Keep credentials out of build arguments to prevent metadata leakage; store API keys in .env.local instead.
• Multiple invocation methods: Works with both docker compose up --build and direct docker build commands.

Frequently Asked Questions

What are the exact requirements for running OpenMAIC on a slow network?

You need Docker with support for build arguments and access to at least one domestic mirror for Alpine Linux (e.g., Tsinghua TUNA) and npm (e.g., npmmirror). No modifications to the application code are required; you only need to inject the ALPINE_MIRROR and NPM_REGISTRY values during the build process as documented in the README.md deployment section.

Do I need to configure Docker Hub mirrors separately?

Yes. The ALPINE_MIRROR and NPM_REGISTRY arguments only affect package installation inside the container build. They do not change how Docker pulls the base image (such as node:22-alpine) from Docker Hub. To speed up base image downloads, configure a Docker daemon registry mirror in your Docker Engine settings separately from the OpenMAIC build configuration.

Are the Chinese mirrors used by OpenMAIC safe to use?

The mirrors referenced in the OpenMAIC source—such as mirrors.tuna.tsinghua.edu.cn and https://registry.npmmirror.com—are public, high-availability mirrors hosted by reputable Chinese universities and cloud providers. They do not require authentication and are widely trusted within the developer community for avoiding international bandwidth constraints.

Can I store mirror URLs in the .env file instead of the command line?

While technically possible, it is not recommended. The OpenMAIC docker-compose.yml is designed to receive build arguments via environment variables at the command line level. Placing mirror URLs in .env.local is unnecessary since these mirrors are public, and keeping them on the command line follows the documented security practice of separating public build configuration from secret runtime variables like API keys.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}