Need NekoBox on your Android TV box? This guide walks through the complete setup using the TV remote: choose the correct APK architecture, sideload it, allow the required installation permission, import a subscription, select a node, and verify that traffic is actually passing through the proxy. The menu names can differ slightly between Android TV, Google TV, and box manufacturers, but the workflow is broadly the same.
Use a recent NekoBox for Android APK that matches your TV box architecture, preferably arm64-v8a on modern hardware. Install it from a trusted local source, permit installation from the file manager only when needed, import a complete subscription or node link, then enable the VPN connection and test a browser page. If the remote makes text entry difficult, prepare the subscription URL with a QR code, USB keyboard, or the TV’s built-in voice input.
Check the TV box and APK compatibility first
Android TV boxes are not identical. Some use 64-bit ARM processors, some still run a 32-bit Android userspace, and a few inexpensive models use x86 hardware. Installing an APK for the wrong architecture can produce messages such as “App not installed,” cause an immediate crash, or leave NekoBox installed but unable to start its core. Check the device before transferring an installer.
Open Settings → Device Preferences → About, or on newer Google TV software, open Settings → System → About. Record the Android version, available storage, and model name. Then look for CPU, Processor, or Build information. If the menu does not expose the ABI, use the box manufacturer’s specification page or a system information utility already installed on the device.
| Item to check | What to look for | Why it matters |
|---|---|---|
| CPU architecture | arm64-v8a, armeabi-v7a, or x86_64 |
The APK must contain a compatible native core and libraries |
| Android version | Compare the minimum version shown by the release information | New builds may not run on an old TV box |
| Storage | Keep at least 1–2 GB free before installation | Android needs space for the APK, extracted files, logs, and updates |
| Network access | Confirm Wi-Fi or Ethernet works without NekoBox | The first subscription update needs a working base connection |
For most Android TV boxes released in recent years, the arm64-v8a package is the first one to try. Do not assume that a box displaying “64-bit CPU” can run every 64-bit APK: the operating system and bundled native libraries also affect compatibility. If a universal APK is offered by the distributor, it may be easier to install, but it can be larger than an architecture-specific package.
Prepare the APK for sideloading
Android TV normally expects applications to arrive through its standard app channel, so a downloaded APK is treated as an unknown source. Sideloading is the process of copying that APK to the box and installing it manually. The simplest method for a remote-only setup is to place the installer on a USB drive, connect the drive to the TV box, and use the built-in file manager. A second method is to download the APK with a browser already installed on the box.
Choose the least troublesome transfer method
USB drive
- Download the APK on another computer
- Copy only the selected installer
- Open it from File Manager
TV browser
- Open the official download page
- Use voice input for the address
- Check the Downloads folder
USB transfer is usually easier when the TV remote cannot enter long URLs accurately; browser download is convenient when no USB port is available.
Format the USB drive as FAT32 or exFAT if your box supports it, then create a simple folder such as Downloads. Avoid putting several similarly named APK files in the same folder. A clear name such as nekobox-android-arm64.apk reduces the chance of opening an old installer by mistake. Safely eject the drive from the computer before connecting it to the TV box.
If the file manager cannot see the drive, check whether the box recognizes the USB device in Settings → Storage. Try another USB port, reconnect the drive after restarting the box, or use a smaller drive formatted with a compatible filesystem. Do not repeatedly download the same APK when the actual problem is that Android TV cannot mount the storage device.
Install NekoBox with the TV remote
The installation process is short, but Android TV may hide the permission behind a security menu. The permission is normally granted to the app that opens the APK, such as File Manager or a browser. It is not a global switch that automatically authorizes every application.
Copy the installer
Insert the USB drive, open File Manager, choose the USB storage, and highlight the NekoBox APK. If the box downloaded it directly, open the browser’s Downloads folder instead.
Allow unknown apps
When Android displays a security warning, select Settings. Open Install unknown apps, choose the current File Manager or browser, and enable Allow from this source.
Start installation
Press the remote’s select button on the APK again. Confirm the package name and requested permissions, then choose Install. Wait until Android reports that the app is installed.
Open NekoBox
Select Open, or return to Settings → Apps → See all apps and launch NekoBox from the application list. Accept only the permissions needed for its VPN operation.
Disable temporary access
After installation, return to Settings → Apps → Special app access → Install unknown apps and turn off the permission for the browser or file manager if you will not install another APK soon.
NekoBox may ask Android to create a VPN connection. This is expected: the local VPN interface allows the application to capture and route traffic from selected apps or from the whole device. When the system confirmation dialog appears, read it and choose OK or Allow. You may see a key icon or VPN indicator in the Android status area after the connection starts.
If the installation stops with “There was a problem parsing the package,” redownload the file and check whether it is a complete APK rather than an incomplete download or an APK bundle requiring a separate installer. If Android says the app is not installed, first verify free storage, remove an older conflicting build if appropriate, and then confirm the architecture. Keep the original APK until NekoBox has started successfully.
Import a subscription on Android TV
A subscription URL normally contains multiple node profiles and may use a long tokenized address. Entering it with a directional remote is slow and increases the chance of changing one character. If the provider supplies a QR code, use NekoBox’s QR import function and place the code where the TV camera or another supported scanner can read it. If QR import is not available, use Android TV voice input, a USB keyboard, or copy the address through a local network transfer method you trust.
Open NekoBox and look for a profile, group, or subscription management screen. The exact labels depend on the NekoBox build and language, but the usual sequence is to choose Add profile, select Subscription or Import from URL, enter a readable name, paste the complete URL, and save it. Do not paste a single node link into a subscription field or paste a subscription URL into a field intended for a local JSON file.
- Use the full URL, including
https://when supplied. - Do not add spaces or quotation marks around the address.
- Keep URL-encoded characters such as
%2Funchanged. - Save the group before pressing update.
- Update only after the TV box has working internet access.
After saving the group, select Update or Refresh. The first update may take longer than later updates because NekoBox must download and decode the complete profile list. When the list appears, inspect one or two entries rather than editing them immediately. A valid imported profile should retain its server address, port, user identifier, transport, security settings, and any required TLS, Reality, WebSocket, or gRPC fields.
For a TV box, avoid importing hundreds of profiles if the provider lets you choose a smaller region or service group. A large list is harder to navigate with a remote and can increase update time. Rename groups with short labels such as Home, Streaming, or Backup. Do not place private subscription tokens in screenshots, chat messages, or public notes.
Choose a node and start the VPN
Select one imported profile and check its details before connecting. The server address and port should not be blank, and a VLESS, VMess, Trojan, or Shadowsocks profile should display the parameters expected by the service. If the profile contains Xray-specific settings such as Reality public key, short ID, server name, or Vision flow control, the selected core must support them. Do not replace a protocol name manually to make an entry look simpler; the server and client parameters must match.
| Profile result | Likely meaning | Next action |
|---|---|---|
| Import succeeds and details are complete | The link was decoded correctly | Run a latency test, then connect to a nearby node |
| Profile name appears but fields are empty | The link format or subscription decoder is incompatible | Update NekoBox, request a compatible link, or import a raw node |
| Latency test times out | The node, route, DNS result, or network may be unavailable | Test another node and compare the result |
| Connects but TV apps fail | The VPN is active but traffic scope or DNS is unsuitable | Review routing mode, app selection, and DNS behavior |
Choose a node with a successful test and reasonable delay, but do not select only by the smallest displayed number. A node showing 80 ms can still buffer if it has congestion or packet loss, while a 150 ms node may play continuously. For the first test, use a geographically nearby node with a stable result. After choosing it, press Connect or the main toggle and approve the Android VPN dialog.
Start with global routing only long enough to verify the installation. If NekoBox provides per-app selection, narrow the scope afterward so that only the TV apps requiring the proxy use it. Local streaming services, device discovery, and applications that must reach your home network may work better outside the proxy. The correct choice depends on the service and the routing rules in the imported profile.
Practical judgment: stability beats the lowest latency
For a TV box, a node that holds a continuous 10-minute video stream without reconnecting is more useful than one that reports the lowest ping but stalls every few minutes. Test playback, pause recovery, and channel switching before keeping a node as the default.
Verify the connection and fix common problems
Do not treat the presence of a VPN icon as proof that every application is using the selected node. Verify the connection in three layers: NekoBox status, basic network access, and an actual TV application. First confirm that NekoBox shows the selected profile as active and that its traffic counters change. Then open a browser page that displays the current public IP or region. Finally, test the application you installed NekoBox for, such as a browser or a supported media service.
Why does the APK install but NekoBox crash immediately?
Check whether the package matches the box ABI, remove an incomplete older build, free at least 1 GB of storage, and install a compatible release again. If only one build crashes, try the architecture-specific package rather than a universal package.
Why does subscription update say timeout?
Turn NekoBox off, confirm that the TV box can open ordinary websites, and retry the update. If the provider permits it, enable update through the currently active proxy; otherwise test the URL in a browser to separate a provider outage from a client problem.
Why does NekoBox connect but the TV app remain unchanged?
Check whether the app is included in the selected VPN scope, then review the routing mode. Some applications use their own DNS, block unfamiliar regions, or cache the previous connection; force-stop the app and test again.
Why is typing the subscription URL nearly impossible?
Use a USB keyboard, Android TV voice input, QR import, or a trusted local transfer tool. A single missing character can invalidate a tokenized URL, so do not try to shorten or retype the address from memory.
If browsing works but streaming buffers, test two other nodes and compare playback for at least five minutes. If every node behaves the same way, inspect the TV box’s Ethernet or Wi-Fi signal, background downloads, time and date, and DNS settings. Incorrect system time can break TLS handshakes, while a weak wireless link can look like a proxy failure.
When NekoBox reports a connection error, open its log view if available and look for the first meaningful line rather than the final generic failure. “Connection refused” often points to an unavailable server port; “TLS handshake timeout” can indicate a route, server name, or time problem; “authentication failed” usually means the profile credentials do not match the server. Reimport the original subscription before changing advanced fields manually.