MengMengCode/VoCat

English | العربية | 简体中文 | 繁體中文 | Français | Русский | Español | 日本語

Vocat is an open-source web control panel and engineering toolkit for Quectel EC20/EC25-class and China Mobile ML307 series cellular modems. It combines modem discovery, live radio status, AT and USSD terminals, SMS, WiFi Calling, eSIM management, network selection, proxy routing, notifications, audit logs, and release automation in one self-contained service.

The backend is written in Go, the interface is built with React and TypeScript, and the production frontend is embedded into the Go binary. A single executable contains the web application and uses SQLite for persistent state.

Vocat targets Qualcomm-based Quectel and China Mobile ML307 series modules that expose compatible AT, QMI, serial, and USB networking interfaces, including:

• Quectel EC20
• Quectel EC25
• Quectel EG25 family
• Compatible EG600 and related modules
• China Mobile ML307 series (e.g. ML307A-E5, various OEMs)

Available features depend on the module firmware, USB composition, SIM/eSIM capabilities, host drivers, radio network, and carrier configuration.

As root (including OpenWrt/Kwrt, where sudo is normally absent):

curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash

From a normal user on a distribution with sudo:

curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | sudo bash

Check the host's VoWiFi/XFRM prerequisites without installing VoCat:

curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash -s -- --check-env

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh -o install.sh
sudo bash install.sh 0.0.2

VoWiFi IMS requires Linux XFRM/IPsec. On OpenWrt/Kwrt the installer attempts to install matching ip-full, kmod-ipsec, kmod-ipsec4/6, kmod-crypto-authenc, AES-CBC and SHA1 packages from the firmware's own feed. If matching kernel modules are unavailable, use a firmware that includes them; never force-install kmods built for a different kernel.

If your kernel cannot provide XFRM/IPsec and you only need non-VoWiFi features such as cellular SMS or data, install with --skip-vowifi-check:

curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh -o install.sh
sudo bash install.sh --skip-vowifi-check

The installer:

• detects amd64, 386, arm64, aarch64, or armv7;
• downloads the matching GitHub Release binary;
• verifies it against SHA256SUMS;
• installs Vocat under /opt/vocat;
• creates a hardened systemd service with the hardware and network access required by Vocat;
• stores runtime configuration in /etc/vocat/env;
• generates a random initial administrator password on first installation.

After installation, open:

http://<server-address>:7575

Download the matching binary and SHA256SUMS from GitHub Releases:

Verify and install it:

sha256sum -c SHA256SUMS --ignore-missing
sudo install -d -m 0755 /opt/vocat/bin /opt/vocat/data
sudo install -m 0755 vocat-linux-amd64 /opt/vocat/bin/vocat
read -rsp "Admin password: " VOCAT_BOOTSTRAP_PASSWORD; echo
printf '%s\n' "$VOCAT_BOOTSTRAP_PASSWORD" | sudo /opt/vocat/bin/vocat bootstrap-admin
unset VOCAT_BOOTSTRAP_PASSWORD
sudo env \
  VOCAT_DATABASE_PATH=/opt/vocat/data/vocat.db \
  /opt/vocat/bin/vocat serve

This manual command runs Vocat in the foreground. Use vocat serve so the process starts the server directly; running vocat without arguments as root on a TTY opens the interactive management menu instead. Use the one-click installer when a managed systemd service and automatic restart are required.

For a Linux host that must discover every attached supported Quectel modem and continue seeing USB hot-plug events, run Vocat in hardware-access mode:

docker pull ghcr.io/mengmengcode/vocat:latest

read -rsp "Admin password: " VOCAT_BOOTSTRAP_PASSWORD; echo
printf '%s\n' "$VOCAT_BOOTSTRAP_PASSWORD" | docker run --rm -i \
  --user 0:0 \
  -v vocat-data:/opt/vocat/data \
  --entrypoint /opt/vocat/bin/vocat \
  ghcr.io/mengmengcode/vocat:latest bootstrap-admin
unset VOCAT_BOOTSTRAP_PASSWORD

docker run -d \
  --name vocat \
  --restart unless-stopped \
  --network host \
  --privileged \
  --user 0:0 \
  -v vocat-data:/opt/vocat/data \
  -v /dev:/dev \
  -v /sys:/sys:ro \
  ghcr.io/mengmengcode/vocat:latest

Open http://<server-address>:7575 after the container starts. Host networking is required so QMI network interfaces remain visible to Vocat, while privileged device access is required for serial ports, QMI control nodes, TUN interfaces, network configuration, and devices added after the container starts. The /dev bind mount makes new ttyUSB*, ttyACM*, cdc-wdm*, and MHI wwan* nodes visible without recreating the container.

This mode intentionally gives Vocat broad access to the host's devices and network stack. Use it only on a trusted Linux host. The automatic discovery identifies supported Quectel USB modems (USB vendor ID 2c7c) and China Mobile ML307 series modules by product string, and PCIe/MHI modems exposed through the Linux WWAN subsystem; it does not identify arbitrary modem layouts. Mapping only individual nodes with --device, such as /dev/ttyUSB2, /dev/cdc-wdm0, or /dev/wwan0qmi0, limits the container to those fixed nodes and does not provide complete multi-device or hot-plug discovery.

The GHCR image is published for linux/amd64 and linux/arm64.

USB SIM readers use the Linux PC/SC service. The one-click installer installs and starts pcscd plus the CCID driver automatically on supported package managers. On Debian/Ubuntu, the equivalent manual setup is apt install pcscd libccid. If USB sees a CCID reader but PC/SC is unavailable, VoCat keeps the reader visible in the add-device dialog and reports the missing service or driver instead of silently hiding it.

VoCat uses qmicli to verify that a QMI control channel is ready and qmi-proxy to multiplex access to it. Packet-data sessions are managed by the built-in QMI WDS client instead of qmi-network CID/PDH state files. The one-click installer installs and verifies the corresponding utilities. For manual deployment, Debian/Ubuntu uses apt install libqmi-utils; Arch Linux uses pacman -S libqmi, Alpine uses apk add qmi-utils, and OpenWrt uses opkg install qmi-utils.

vocat doctor --repair-dji-qmi checks for qmicli before changing any USB driver binding or asserting DTR. If the utility is unavailable, the command stops with an installation hint and leaves the current device state untouched.

Vocat reads an optional JSON configuration file from VOCAT_CONFIG, then applies VOCAT_* environment variables. Environment variables take precedence.

User-supplied Apple carrier bundles can be converted into reviewable, allow-listed carrier profiles with vocat carrier import-ipcc; see docs/CARRIER_IPCC_IMPORT.md.

Administrator credentials are stored only in SQLite. Initialize an empty database once with vocat bootstrap-admin; environment variables and JSON configuration cannot set or overwrite the administrator username or password.

Do not store Telegram tokens, SMTP passwords, webhook secrets, SIM credentials, or other private data in the repository. Configure them through the application settings or protected environment files.

When Telegram notifications are enabled and both Chat ID and Admin ID are configured, the bot supports:

/status [device]
/esim <device>
/switch <device> <iccid>
/wfc <device> <status|on|off|reconnect>
/sms <device> <number> <message>

Profile switching and SMS submission use one-time confirmation buttons. The bot does not expose eSIM download, delete, or rename commands.

Check for a newer GitHub Release:

vocat update --check --repo MengMengCode/VoCat

Install the latest release:

sudo vocat update --repo MengMengCode/VoCat

The updater downloads the binary matching the current Linux architecture, verifies it with the published SHA256SUMS, replaces the executable atomically, and restarts the vocat systemd service when available.

For Docker installations:

docker pull ghcr.io/mengmengcode/vocat:latest

Recreate the container after pulling the new image.

Requirements:

• Go 1.25 or newer
• Node.js 20 or newer
• npm

Run the frontend development server:

cd web
npm install
npm run dev

Build the embedded frontend and start the backend:

cd web
npm run build
cd ..
go run ./cmd/vocat

Run all tests:

go test ./...

Build a production binary:

go build -trimpath -ldflags "-s -w" -o vocat ./cmd/vocat

Pushing a version tag starts two GitHub Actions workflows:

• release-binaries builds and publishes amd64, 386, arm64, aarch64, and armv7 binaries plus SHA256SUMS.
• docker builds and publishes a multi-architecture image to GitHub Container Registry.

git tag v0.2.0
git push origin v0.2.0

cmd/vocat/                  Application entry point and CLI
internal/device/            Modem discovery and device control
internal/modem/             AT session and response handling
internal/server/            HTTP API, notifications, and embedded web server
internal/store/             SQLite persistence
internal/update/            GitHub Release self-updater
internal/vowifi/            IKE, EAP-AKA, IMS, and WiFi Calling runtime
scripts/install.sh          Linux installer and updater
web/src/                    React and TypeScript frontend
.github/workflows/          Binary and Docker release automation

Cellular modem and eSIM operations can affect subscriber service, stored profiles, network registration, and hardware state. Keep backups, review destructive actions carefully, and use the software only in lawful environments where you are permitted to operate the connected hardware and network resources.

Vocat does not bypass carrier authentication, network policy, hardware security, or eSIM trust requirements. Support for an operation means that Vocat can request it from the modem or eUICC; the device, profile, network, or carrier may still reject it.

Issues and pull requests are welcome. Keep changes focused, include tests where practical, avoid committing credentials or subscriber data, and document hardware-specific behavior clearly.

Before submitting a change:

go test ./...
cd web && npm run build

• Nodeseek.com — A community dedicated to servers
• Linux.do — An inspiring tech community
• iniwex5 — Style and Functionality Guidelines

See LICENSE.