en US deployment macos

macOS: From Extraction to First Login

The macOS package hosts the main service and NodeAgent via launchd LaunchDaemon, supporting both Intel and Apple Silicon. While development machines can perform foreground debugging, long-term operation should be installed as a system service.

flowchart LR
    A[Confirm Intel / Apple Silicon] --> B[Extract and run installer]
    B --> C[launchd manages service and Agent]
    C --> D[Open port 5800 and finish setup]

Loading

1. Confirm Architecture

uname -m

arm64 Use osx-arm64, and x86_64 use osx-x64. The local machine also requires the .NET 7 ASP.NET Core Runtime; this can be verified using dotnet --list-runtimes.

2. Verification and Extraction

shasum -a 256 AKStream.Next-<version>-osx-arm64.tar.gz
tar -xzf AKStream.Next-<version>-osx-arm64.tar.gz
cd AKStream.Next-<version>-osx-arm64
./Deploy/macos/akstream-next.sh --help

Compare the calculated result with the SHA256 record of the same Release. For the meaning of directories within the package, see Package Structure.

3. Install LaunchDaemon

sudo ./Deploy/macos/akstream-next.sh install \
  --package-dir "$PWD"

Default locations:

• Programs and Data: /Library/Application Support/AKStream.Next
• Configuration: /Library/Application Support/AKStream.Next/Config
• Main Service Label: com.akstream.next
• Agent Label: com.akstream.next.agent

The installer registers the plist under /Library/LaunchDaemons, and launchd is responsible for automatically starting it. Do not install service files into a personal user's temporary directory.

Before installation, make sure port 5800 is not occupied by another AKStream.Next instance, a Docker port mapping, or another process. The installer verifies that the listener PID belongs to the com.akstream.next LaunchDaemon; an HTTP 200 from an unrelated process is not accepted as installation success. For browser-downloaded packages, com.apple.quarantine is removed only from the AKStream.Next, NodeAgent, and ZLMediaKit component directories inside the fixed package boundary. Gatekeeper remains enabled, and files outside the package are not trusted.

lsof -nP -iTCP:5800 -sTCP:LISTEN
docker ps --format '{{.Names}}\t{{.Ports}}'

4. Complete Initial Configuration

sudo cat '/Library/Application Support/AKStream.Next/Config/.akstream-next-setup-token'
curl -fsS http://127.0.0.1:5800/health
curl -fsS http://127.0.0.1:5800/api/v2/setup/status

During first installation, the last command must return "required": true. If it returns "required": false, or /health identifies another version or node, stop the old instance or Docker container that owns port 5800 and run sudo akn restart. Open http://127.0.0.1:5800/ or a LAN-reachable address in a browser and follow the Setup Wizard to complete the installation. Upon completion, the main process will exit and be restarted by launchd in full mode.

5. Status, Start/Stop, and Logs

akn status
sudo akn restart
sudo akn stop
sudo akn start

You can also check launchd:

sudo launchctl print system/com.akstream.next
sudo launchctl print system/com.akstream.next.agent

If the application is running but the page cannot be opened, first check /health, listening ports, and the macOS firewall, then check the configuration and MediaServer; do not repeatedly reinstall.

6. Common Misconceptions on Apple Silicon

• osx-arm64 The main program, MediaServer, FFmpeg, and dynamic libraries must all be ARM64; you cannot replace only one of them.
• Homebrew is often located at /opt/homebrew on Apple Silicon, but scripts detect the actual command location; do not hardcode paths into business configurations.
• The official release already includes the required media component; installation hosts do not need a media-component build toolchain.

7. Upgrade, Recovery, and Uninstallation

Use the script from the new package to execute install --package-dir "$PWD" again to complete the upgrade. Previous versions of the program and Agent are retained as *.backup, but configuration, databases, and recordings must still be backed up separately.

verify-recovery will interrupt the main process and should only be used during maintenance windows:

sudo akn verify-recovery

Interactive uninstallation chooses between retaining data and complete cleanup, and confirms complete cleanup again. --purge --yes is only for unattended operation:

sudo akn uninstall

Next Step: Management Command Quick Reference.

Third-party dependency sources

The installer prefers verified Chinese mirrors. Debian/Ubuntu (including ARM Ubuntu Ports) and mapped RPM repositories use temporary source settings and retain distribution signature checks; failure falls back to the original official/configured sources. macOS uses USTC Homebrew API and Bottles for FFmpeg, databases, Nginx and build dependencies, with an official-source fallback and no permanent environment changes. The required ASP.NET Core Runtime currently has no verified stable Chinese mirror in this installer and uses Microsoft. Source selection does not change architecture, runtime type or version requirements.