3x-ui Offline On MikroTik RB4011 (ARMv7)

Introduction: Why Install 3x-ui Offline on MikroTik?

Installing containers on MikroTik RouterOS typically involves downloading container images from an external registry.

However, direct downloads may fail because of restricted network access, unreachable repositories, routing limitations, or registry-related errors.

In these situations, an offline container installation can provide an alternative.

Instead of downloading the image directly on the router, administrators can obtain a compatible image using another computer, prepare it as a container archive, and transfer it to MikroTik through Winbox.

RouterOS can then extract and install the image locally without contacting an external container registry during installation.

Important: An offline installation does not mean that the resulting service operates without internet connectivity. The management panel may require network access for some operations, while Xray requires appropriate connectivity to communicate with configured destinations.

This guide explains how to install a prebuilt ARMv7 image of 3x-ui on a compatible MikroTik router.

Can 3x-ui Run on Every MikroTik Router?

No. Not all MikroTik devices support the same container workloads.

Before proceeding, administrators must verify:

RouterOS container support
CPU architecture
Available RAM
Internal or external storage capacity
Compatibility of the container image

A container image designed for an AMD64 VPS will not necessarily run on an ARM-based MikroTik router.

Hardware Used in This Example

The tested installation used the following configuration:

Component	Specification
Router	MikroTik RB4011iGS+5HacQ2HnD
CPU Architecture	ARM
RAM	1 GB
Internal Storage	512 MB
Container Architecture	ARMv7
RouterOS Version	7.24.5
3x-ui Version	3.10.2

To check your router’s specifications, run:

/system resource print

The example installation successfully imported the 3x-ui version 3.10.2 image and confirmed a Running container state on RouterOS 7.24.5.

However, this result should not be interpreted as a complete validation of every supported protocol, user capacity, or performance level across all MikroTik models.

Storage Requirements: An Important Consideration

One of the most important considerations when running containers on MikroTik hardware is storage capacity.

The downloaded container archive is compressed.

During extraction, RouterOS may temporarily need enough storage for both the original archive and the extracted filesystem layers.

In this installation example:

Storage Item	Approximate Size
Container archive	114 MB
Extracted container layers	316 MB

Additional free space is necessary for application data, filesystem operations, and existing router files.

Common Storage Error

You may encounter this message:

could not save configuration changes,
not enough storage space available

This indicates insufficient available storage.

Repeatedly uploading or attempting to install the container without addressing the storage issue may make the situation worse.

Before removing any files, identify their purpose.

In particular, the container root directory may contain application files and important panel data.

Deleting it without a verified backup may result in permanent data loss.

Step 1: Install and Enable RouterOS Container Support

First, verify whether the Container package is installed:

/system package print where name="container"

If the package is missing, download the matching Container NPK file from the official MikroTik Extra Packages distribution.

The package must match:

The exact RouterOS version
The router’s processor architecture

Upload the NPK file using Winbox under Files.

Reboot the router to complete installation.

Check Device Mode

After the package has been installed, run:

/system device-mode print

If the container feature is disabled, enable it with:

/system device-mode update container=yes

Confirm the Device Mode Change

MikroTik requires physical confirmation for this operation.

Depending on the hardware, the confirmation process may involve temporarily disconnecting and reconnecting power or another supported physical action.

The confirmation must be completed within the time specified by RouterOS.

A regular software reboot does not count as physical confirmation.

Once the router returns online, verify that the container feature is enabled:

container: yes

Step 2: Configure the Container Network

The 3x-ui container needs an IP address and a default gateway.

A common approach is to create a dedicated bridge and attach a VETH interface to it.

In this example, the container network is:

172.17.0.0/24

Before using this subnet, ensure that it does not overlap with an existing LAN, VPN, or other routed network.

Create a Container Bridge

/interface bridge add name=containers

Assign the Gateway Address

/ip address add address=172.17.0.1/24 interface=containers

Create the VETH Interface

/interface veth add name=veth1 address=172.17.0.2/24 gateway=172.17.0.1

Connect VETH to the Bridge

/interface bridge port add bridge=containers interface=veth1

The container will use:

Container IP: 172.17.0.2
Gateway:      172.17.0.1
Subnet:       172.17.0.0/24

Note: If these interfaces or addresses already exist, do not recreate them. Adjust the configuration to match your existing network.

Configure Outbound NAT

The container may require NAT to access external networks.

If your existing NAT configuration does not already cover the container subnet, and WAN is the correct outbound interface list, you can add:

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

This rule allows source NAT for traffic originating from the container network.

Configure Firewall Forwarding

NAT alone does not guarantee that LAN devices can communicate with the container.

The RouterOS firewall must also permit the appropriate traffic between trusted management networks and the container subnet.

Add only the necessary forward rules, using the actual source and destination addresses in your environment.

Place rules before any matching drop rules where required.

Do not disable the entire firewall to troubleshoot connectivity.

Step 3: Upload the Offline ARMv7 Image

After preparing the container network, transfer the prebuilt image archive to the router.

Open Winbox → Files.

Upload the following file:

3x-ui-mikrotik-armv7.tar.gz

Do not extract this .tar.gz archive on your computer.

RouterOS will extract the image during the container import process.

After the transfer completes, verify the file:

/file print detail where name="3x-ui-mikrotik-armv7.tar.gz"

Architecture Compatibility Warning

The example filename identifies an ARMv7 container build.

Simply renaming an AMD64 or another incompatible image to include armv7 does not make it compatible with ARM hardware.

Always verify the actual architecture of the container image.

Step 4: Import and Start the Container

Once the archive is present in RouterOS Files and the VETH interface is configured, import the image:

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

This command uses the local archive through the file parameter.

Unlike the online installation method, it does not require remote-image or a container registry for the import operation.

Monitor the Import Process

Run:

/container print

You can also check logs:

/log print where topics~"container"

During extraction, RouterOS may display an E flag.

Do not repeatedly execute the import command or delete the archive while extraction is in progress.

Start the Container

After extraction, if the container has not started automatically, start it using its actual name.

For the example container name:

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

Then verify:

/container print detail

A container with the R flag is running.

However, a running container does not automatically mean that the web interface or every application service is fully operational.

Application logs and browser connectivity should also be checked.

Step 5: Access the 3x-ui Web Management Panel

In this example, the container IP address is:

172.17.0.2

If the management panel is configured to use port 2053 over HTTP, the initial test URL is:

http://172.17.0.2:2053

Open the address from a computer that can reach the container network through the MikroTik router.

The actual installation may use:

HTTPS instead of HTTP
A different management port
A custom web path
Different authentication credentials

The management port and URL must be verified from the application configuration rather than assumed.

Check 3x-ui Settings from the Container

If you are unsure about the panel configuration, open a shell inside the running container.

For the example container name:

/container shell [find where name="3x-ui-mikrotik-armv7"]

Inside the container’s Linux shell, run:

cd /app
./x-ui setting -show true

This command is intended to display configuration information for the version used in this example.

If the command is not supported by your build, refer to the corresponding version’s CLI documentation.

The output may contain sensitive configuration information and should not be shared publicly.

After the first successful login, configure a strong administrator password.

Management Port vs. User Inbound Ports

The 3x-ui management interface port is separate from the inbound ports used for client connections.

Creating an inbound connection requires additional configuration, including the appropriate protocol, listening port, and network access rules.

Being able to open the management panel does not automatically mean that client connections are configured or functional.

Step 6: Do You Need Ubuntu Inside the Container?

No. A separate Ubuntu installation is not required for the prebuilt image used in this guide.

The example 3x-ui container image is based on Alpine Linux and already includes the required application components.

Running an additional Ubuntu container and manually installing 3x-ui would introduce more installation steps and dependencies without being necessary for this deployment.

However, if a specific application requires Ubuntu-only tools or dependencies, a different container image may need to be developed and tested.

Containers Are Not Full Virtual Machines

RouterOS containers should not be treated exactly like conventional Ubuntu VPS installations.

In particular, commands designed for environments using systemd may not behave the same way inside a minimal container image.

Use the execution model intended for the container build.

Step 7: Preserve 3x-ui Data After Reboots and Upgrades

Data persistence is essential for maintaining a reliable 3x-ui installation.

A normal container stop/start cycle or router reboot should not intentionally erase application data as long as the container root directory remains intact on persistent storage.

The configuration option:

start-on-boot=yes

enables automatic container startup after a router reboot.

However, several operations may result in data loss:

Deleting the container root directory
Rebuilding the container without preserving data
Removing application files during storage cleanup
Performing Netinstall without adequate backups

Back Up the Database

Use the application’s available backup functionality to export its database.

Store backups outside the MikroTik router.

Certificates, private keys, and separately imported configuration files should also be backed up.

A MikroTik configuration export is not a replacement for backing up container files and databases.

Use Persistent Mounts for New Deployments

For new installations, the application’s /etc/x-ui/ directory can be mapped to a dedicated persistent storage location.

This can make future image replacement and data preservation easier.

For an existing installation containing valuable data, do not attach an empty directory directly over the application’s data path.

First:

Create a verified backup.
Stop the container in a controlled manner.
Transfer existing application data.
Configure the appropriate persistent mount.
Restart the service and verify its configuration.

This process reduces the risk of hiding or losing existing application data.

Troubleshooting Common Installation Issues

Error: Architecture Mismatch

This usually indicates that the container image architecture is incompatible with the router’s processor.

Verify the CPU architecture and obtain the correct container build.

Error: 404 During Online Download

An HTTP 404 error during an online installation typically points to an incorrect or unavailable repository path.

This is different from a local archive extraction failure.

If a compatible local image is available, the offline import method can avoid relying on the registry during installation.

Error: Not Allowed by Device Mode

This indicates that the required container functionality has not been enabled through RouterOS Device Mode.

Repeat the Device Mode verification and complete the necessary physical confirmation.

Error: Not Enough Storage Space

Inspect the available storage before trying again.

Old installation files and unused container images may consume significant space.

Avoid deleting active container directories or application databases without backup verification.

Container Is Running but the Panel Does Not Open

If RouterOS displays the R flag but the management interface remains inaccessible, check the following in order:

Application logs
Container IP address
Actual web management port
HTTP or HTTPS configuration
Any configured custom web path
Routing between the management computer and container network
RouterOS firewall forward rules

Also verify that the application process itself has started correctly.

A shell process kept alive by a command such as tail does not prove that the 3x-ui service is running.

Avoid modifying the image’s original EntryPoint or CMD unless there is a specific technical reason.

Best Practices for Reliable Operation

For a stable installation, make sure the router has sufficient free storage and memory for both RouterOS and the application.

Use a container image that matches the CPU architecture, preserve application data, and maintain backups outside the device.

Restrict management access to trusted systems and use secure authentication.

For production use, prefer HTTPS and avoid exposing administrative services directly to untrusted networks.

Finally, confirm application availability and the required network functions instead of relying solely on the RouterOS container running indicator.

Conclusion

Installing 3x-ui offline on MikroTik RouterOS is a practical alternative when direct container registry access is unavailable or unreliable.

By importing a compatible container archive from local storage, administrators can complete the installation without requiring RouterOS to download the image from a registry.

Successful deployment depends on choosing the correct CPU architecture, providing adequate storage, configuring a non-overlapping container network, and verifying that the application is actually running.

After installation, maintaining external backups and separating persistent application data from replaceable container files can simplify future upgrades and recovery.

Official References and Resources

Technical Note: This tutorial documents a specific installation example. Network addresses, firewall policies, storage layouts, and application settings must be adjusted for the target environment. Distributing a container image alongside the article requires appropriate version maintenance and compliance with the licenses of its bundled software.

3xUI.zip Download

How to Install 3x-ui Offline on MikroTik RouterOS: Complete ARMv7 Container Guide