# Requirements for Running OpenMAIC on a Slow Network or in China

> Run OpenMAIC on slow networks or in China by setting Alpine mirror and npm registry build args. Deploy OpenMAIC with ease in restricted environments.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.

```bash
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:

```bash
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.

```bash
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.