> For the complete documentation index, see [llms.txt](https://docs.seedex.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.seedex.net/developer-guide/seedex-box.md).

# seedex-box

This page describes how the seedex-openwrt repository is laid out and how to build and lint it.

## Requirements

* Docker, for the build. It hosts the apk-tools that builds the packages.
* shfmt 3.13 and shellcheck 0.11, for the lint.
* A router running OpenWrt 25.x or later with `apk`, to install a build.
* Optionally, an apk signing key in `~/.seedex/apk-sign.key`. Without the key, the packages are unsigned and `install.sh` installs them with `--allow-untrusted`.

## Project structure

`seedex-box/files/` contains the router package:

* `usr/bin/sdx`: The command: dispatch, status, and help.
* `usr/bin/seedex-router-watchdog`: Probes the tunnels and switches the overlay.
* `usr/lib/seedex/common.sh`: Shared helpers: UCI, nftables sets, probes, and status lines.
* `usr/lib/seedex/service.sh`: What every service shares: entries, apply, enable, and import.
* `usr/lib/seedex/vpn.sh`, `proxy.sh`, `router.sh`, and `dns.sh`: One library per service.
* `usr/lib/seedex/link.sh`: The link: pairing, sync, selection, and remote commands.
* `etc/init.d/seedex`: The umbrella service that starts the others in order.
* `etc/init.d/seedex-*`: One procd service per module.
* `etc/config/seedex-*`: Documented UCI configs, empty by default.
* `etc/hotplug.d/net/50-seedex-proxy`: Attaches the proxy interface when sing-box brings it up.

`seedex-box/package/` contains the apk scripts for installation, upgrade, and removal.

`luci-app-seedex/files/` contains the LuCI app:

* `usr/libexec/rpcd/luci.seedex`: The rpcd backend that LuCI talks to. It runs `sdx`.
* `www/luci-static/resources/seedex/api.js`: The JavaScript client of the backend and the shared widgets.
* `www/luci-static/resources/view/seedex/*.js`: One view per tab.

At the top level, `build.sh` builds the packages, `install.sh` is the script that users run, and `version` holds the version.

## Build

Run the following command:

```sh
make build
```

The command builds `seedex-box` and `luci-app-seedex` into `build/noarch/`, together with the feed index, and puts the public key in `build/keys/`.

To install the build on a router, copy `install.sh`, `build/keys`, and `build/noarch` to the router and run `sh install.sh noarch/*.apk` there.

## Lint

`make lint` runs shfmt and shellcheck over every shell file.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.seedex.net/developer-guide/seedex-box.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.