How to Install 3x-ui Offline on MikroTik RB4011 (ARMv7)

When a MikroTik router cannot reach a container registry, an online image pull may fail before installation even begins. An offline image import can avoid that dependency: prepare a compatible container image on another computer, transfer it to the router, then import it locally.

This guide describes the example installation of 3x-ui on a MikroTik RB4011 using RouterOS 7 and an ARMv7 image. It covers the checks that matter most—architecture, Container support, storage, network access, and keeping panel data recoverable. A successful import on one router does not establish compatibility with every MikroTik model or validate every 3x-ui feature.

Project scope: The upstream 3x-ui project describes itself as intended for personal use and says not to use it for illegal purposes or in a production environment. Review the project guidance before proceeding. MikroTik also warns that third-party container images increase a router’s security exposure. Use an image you trust and keep its management interface restricted.

What “offline installation” means

In this workflow, the router does not need to download the container image from a registry during installation. The image is transferred to the router in advance and imported from its local Files area.

That does not make the running service independent of networking. The panel and its Xray services still need an appropriate network path for their intended operation. Plan DNS, routing, firewall rules, and administration access for your environment.

Check whether your MikroTik can run the image

Do not assume that a container built for an AMD64 VPS will run on an ARM router. Confirm the device architecture, RouterOS version, available memory, and free storage first:

/system resource print
/system package print
/system device-mode print

The supplied example image is for ARMv7 and was tested in the source guide on an RB4011 (architecture arm) with RouterOS 7.24.5 and 3x-ui 3.10.2. The image file is approximately 114 MB, while the extracted layers in that example use about 316 MB. Keep additional working space available for existing files and updates. A different router requires its own architecture and storage check.

If the router reports low storage, stop and inspect the installation before uploading or retrying. The extracted container root may contain panel data. Deleting it to make room can remove the configuration you are trying to preserve.

Step 1: Install and enable the RouterOS Container package

If the Container package is not installed, download the Extra package that matches both the router’s RouterOS version and architecture from the official MikroTik downloads page. Extract the package archive, upload the matching NPK file to the router’s Files area, and reboot so RouterOS can install it.

Then check Device Mode. If Container is disabled, request the change:

/system device-mode update container=yes

RouterOS requires physical confirmation for some Device Mode changes. Follow the timing and confirmation method shown by the router, then reconnect and verify that Container is enabled. A regular reboot does not replace the physical confirmation step.

Step 2: Prepare a container network

The container needs an IP address and gateway. The example uses a separate 172.17.0.0/24 network, with the router at 172.17.0.1 and the container at 172.17.0.2. Check that this subnet does not overlap with an existing LAN, VPN, tunnel, or route before using it.

/interface bridge add name=containers
/ip address add address=172.17.0.1/24 interface=containers
/interface veth add name=veth1 address=172.17.0.2/24 gateway=172.17.0.1
/interface bridge port add bridge=containers interface=veth1

If the container needs outbound internet access and existing NAT does not already cover its traffic, an example masquerade rule is:

/ip firewall nat add chain=srcnat src-address=172.17.0.0/24 out-interface-list=WAN action=masquerade comment="3XUI outbound NAT"

Replace WAN and all example addresses with values that match the router. NAT does not by itself permit LAN access to the panel. Review forward-chain rules and their order so only the intended source networks and ports can reach the container. Do not disable the firewall to troubleshoot connectivity, and do not expose the management panel directly to the public internet.

Step 3: Transfer the ARMv7 image

In WinBox, open Files and upload 3x-ui-mikrotik-armv7.tar.gz to the router. Keep it compressed; RouterOS imports the archive. Confirm that the uploaded filename and location match the command you will use.

The prepared image is an example package. Renaming an image built for a different processor does not convert its architecture.

Step 4: Import and start 3x-ui

Once the bridge and virtual Ethernet interface are ready, the source guide’s example command is:

/container add file=3x-ui-mikrotik-armv7.tar.gz interface=veth1 root-dir=3xui-root start-on-boot=yes logging=yes

This uses the local file parameter, so the router does not need a registry pull for the import. Run the add command once and wait for extraction to finish. Check the container status and RouterOS logs rather than repeating the import or deleting files while extraction is in progress.

/container print
/log print where topics~"container"

When extraction completes, start the container if it is not already running, using the actual name shown on your router:

/container start [find where name="3x-ui-mikrotik-armv7"]
/container print detail

An R status indicates a running container process, but it does not prove the web panel is reachable or that every service is healthy. Check the logs and test from a computer with a valid route to the container.

Step 5: Open the panel safely

In the sample network, the initial panel address is http://172.17.0.2:2053/. Your deployment may use a different port, HTTPS, or a custom web path. Use the settings from your actual container rather than assuming the sample defaults.

The management panel port is separate from ports used by configured inbounds. If the settings need to be inspected from the container shell, the source guide uses:

/container shell [find where name="3x-ui-mikrotik-armv7"]
cd /app
./x-ui setting -show true

Command output may include sensitive settings. Keep it out of public screenshots, logs, and support requests. After first access, set a strong unique administrator password. Keep the management interface limited to a trusted administration network or an approved secure remote-access path.

Do you need Ubuntu in the container?

Not for the prepared image described here. The source guide’s package is based on Alpine and includes the components needed for its intended purpose. A container is not a full virtual machine, so systemd-based VPS instructions do not necessarily apply. If you have a separate requirement for Ubuntu tools, choose and test a different image rather than changing the working image’s startup command without a clear reason.

Keep panel data through restarts and upgrades

A normal router reboot or container Stop/Start does not intentionally erase data when the container root remains on persistent storage. However, deleting the root directory, rebuilding the image, cleaning the storage device, or reinstalling RouterOS can remove the panel database and configuration.

Use the panel’s database backup feature and store backups away from the router. Back up certificates and keys separately if you manage them outside the database. A RouterOS configuration export is not a backup of files and data inside the container.

For a new installation, the 3x-ui data path may be mounted separately. Do not attach an empty mount over an existing panel that already contains data. Back up first, stop the service in a controlled way, migrate the existing data, and verify it before restarting. Never run two copies against the same data directory at once.

Troubleshooting common errors

• Architecture mismatch: check the router architecture and use a compatible image.
• “Not allowed by device-mode”: confirm Container is enabled and the required physical confirmation completed.
• Registry 404: this describes an online image pull. For the offline workflow, verify the local file name and use the file import method.
• Not enough storage: inspect free space and existing container data before making changes. Do not retry uploads blindly.
• Container runs but the panel does not open: check application logs, container IP, port, protocol, web path, routing, and forward rules.
• The container exits soon after start: use the logs to find the application error. Keeping a shell process alive does not mean the panel is running.

Frequently asked questions

Can I install this ARMv7 image on any MikroTik router?

No. Confirm the router architecture and RouterOS Container support first. ARMv7 is not interchangeable with ARM64 or x86 images.

Does offline import mean 3x-ui no longer needs internet access?

No. It only removes the router’s need to fetch the image from a registry during installation. Runtime networking depends on how the service is configured and used.

Does a running container mean the panel is ready?

Not by itself. Check application logs, confirm the configured web address, and test access from the intended management network.

Where can I find official technical references?

See MikroTik’s documentation for Container, Device Mode, and packages, plus the 3x-ui project. For help tailoring the deployment to a network, contact System Support Canada.

Plan the installation around the router you have

An offline 3x-ui import can help when a registry is unreachable during setup. A stable deployment still depends on the right architecture, adequate storage, a non-overlapping container subnet, restricted management access, and backups outside the router. Treat the example addresses and firewall rules as starting points to review against your own RouterOS configuration.