Egress Gateway#

Egress Gateway is Luma's outbound proxy plane.

It solves two practical problems:

• domestic servers may fail to pull fresh images or dependencies directly;
• some services must access external networks while the public entrypoint remains domestic.

Egress is not an ingress path. Public user traffic still enters through the selected exposure mode.

Setup#

export EGRESS_SUBSCRIPTION_URL='...'
luma manager egress

Luma will:

• download the subscription;
• convert YAML or base64 subscription output into a minimal Mihomo config;
• write /opt/luma/egress-gateway/config.yaml with mode 600;
• configure stable system DNS resolvers for registry/bootstrap reliability;
• temporarily disable Docker daemon proxy for the first egress bootstrap;
• deploy the core egress-mihomo Nomad job using Luma's built-in egress image;
• mark the gateway host as egress=true (Nomad client meta) for the internal egress_mihomo service;
• install Docker-aware public port guards for the egress proxy;
• configure Docker daemon proxy to 127.0.0.1:7890;
• restart Docker.

The default egress image is a domestic registry mirror tested for first bootstrap:

defaults:
  images:
    egressGateway: docker.1panel.live/metacubex/mihomo:latest

Most users do not need to configure an image. Advanced users can override defaults.images.egressGateway in luma.yaml when operating their own registry mirror.

Refresh later:

luma manager egress

Runtime#

The gateway listens on:

127.0.0.1:7890

The egress proxy is reachable to local Docker and to services that opt in with proxy: true. Luma installs host firewall, raw PREROUTING, and Docker DOCKER-USER guards so Docker-published 7890/tcp and 7890/udp are blocked on the public default interface while local Docker and internal egress traffic can still use the proxy.

Docker daemon proxy:

HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890
NO_PROXY=localhost,127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

Verify#

nomad job status egress-mihomo
sudo docker pull hello-world:latest

For a service that needs the runtime proxy, declare proxy: true in the service manifest:

name: ai-worker
image: ghcr.io/acme/ai-worker:1.0.0
region: cn
exposure: none
proxy: true

Luma injects HTTP_PROXY=http://egress_mihomo:7890 and HTTPS_PROXY=http://egress_mihomo:7890 automatically. Scheduling still follows the service region. If the manifest already sets HTTP_PROXY or HTTPS_PROXY, Luma keeps the explicit value.

Security#

• Do not commit EGRESS_SUBSCRIPTION_URL.
• Rotate subscription URLs that appear in chat, logs, or screenshots.
• Keep inbound 7890 blocked on public interfaces. Luma installs this guard during bootstrap and egress setup; re-run luma manager egress if host firewall rules were reset manually. Luma's built-in egress service has its own Nomad resource limits. Budget its memory in addition to Control's 4 GiB reservation, the operating system and other workloads.
• Prefer one egress gateway first. Add more only when scheduling or throughput requires it.