whitestarcommunications/synology-hyperspaceserviceagent repository overview

⁠HyperSpace Service Agent For Synology NAS

Primary HyperSpace service workload with REST and CLI endpoints.

⁠What This Agent Does

Expose services securely through HyperSpace.

This image is the Synology-specific distribution of HyperSpace Service Agent. It is meant to be installed and maintained from an SSH session on the NAS, not from the Container Manager launch wizard.

Repository: whitestarcommunications/synology-hyperspaceserviceagent

Current release tag:

• 0.04.16.26.4

⁠Before You Start

The NAS needs:

• Container Manager installed
• an SSH account that is allowed to run sudo
• /dev/net/tun available, or permission for the installer to create it

The installer uses sudo because it may need to:

• create /dev/net/tun
• run modprobe tun
• create persistent folders under /volume1/...
• replace an earlier container of the same name

⁠Step 1: Sign In To The NAS

Connect to the Synology host with an account that is allowed to run sudo.

ssh <synology-user>@<nas-host>

You do not need to switch to an interactive root shell first. The setup block below uses sudo for the commands that need it, but you should validate sudo before you paste any setup commands.

⁠Step 2: Authenticate Sudo First

Do not continue until this succeeds. The Synology setup path needs elevated privileges for Docker access, TUN preparation, and persistent-directory creation.

sudo -v

If your environment prefers a root shell, use sudo -i instead and then run the next steps from that shell.

⁠Step 3: Pull The Image And Extract The Installer Bundle

Each Synology image now carries its own NAS-side installer bundle at /opt/hyperspace-synology. The block below pulls the exact image from Docker Hub and copies that bundled installer onto the NAS filesystem.

The extracted directory contains:

• install.sh
• update.sh
• clean.sh
• .env
• README.md

That local directory is what you will execute on the NAS.

set -euo pipefail

IMAGE='whitestarcommunications/synology-hyperspaceserviceagent:0.04.16.26.4'
BUNDLE_ROOT='/volume1/docker/hyperspace-installers'
BUNDLE_DIR="${BUNDLE_ROOT}/service-0.04.16.26.4"
TEMP_CONTAINER='hyperspace-service-bundle-extract'
if [ "$(id -u)" -eq 0 ]; then
  SUDO=''
else
  echo "This setup requires sudo or a root shell before it will touch Docker or NAS storage." >&2
  command -v sudo >/dev/null 2>&1 || {
    echo "This setup requires sudo or a root shell." >&2
    exit 1
  }
  sudo -v || {
    echo "sudo authentication failed. No setup commands were run." >&2
    exit 1
  }
  SUDO='sudo'
fi
command -v docker >/dev/null 2>&1 || {
  echo "Docker CLI is not installed on this NAS." >&2
  exit 1
}
${SUDO} docker info >/dev/null

${SUDO} docker pull "${IMAGE}"
${SUDO} mkdir -p "${BUNDLE_ROOT}"
${SUDO} rm -rf "${BUNDLE_DIR}"
${SUDO} mkdir -p "${BUNDLE_DIR}"
${SUDO} docker rm -f "${TEMP_CONTAINER}" >/dev/null 2>&1 || true
${SUDO} docker create --name "${TEMP_CONTAINER}" "${IMAGE}" >/dev/null
${SUDO} docker cp "${TEMP_CONTAINER}:/opt/hyperspace-synology/." "${BUNDLE_DIR}"
${SUDO} docker rm -f "${TEMP_CONTAINER}" >/dev/null
cd "${BUNDLE_DIR}"
ls

If you want the installer stored somewhere else on the NAS, change BUNDLE_ROOT before you run the block.

⁠Step 4: Run The Installer

From the extracted bundle directory on the NAS:

cd /volume1/docker/hyperspace-installers/service-0.04.16.26.4
sudo ./install.sh

install.sh handles the full host setup:

• creates the persistent directories
• prepares /dev/net/tun when the NAS allows it
• pulls the agent image if needed
• removes any older container with the same name
• starts the new container with the correct device mapping, capabilities, ports, and mounts

The created container should appear in Synology Container Manager after the command finishes.

⁠What Those Folders Are For

By default, install.sh creates three persistent folders under:

• /volume1/HyperSpaceServiceAgent

Those directories are:

• state: long-lived HyperSpace state and identity data
• log: runtime logs
• agent: profile-specific runtime files under /root/serviceAgent

These folders are important because they let the agent keep its state when you replace the container with a newer image.

⁠Day-2 Operations

The generated SSH bundle includes three commands:

• install.sh: first install or replace the current container
• update.sh: pull a newer image tag and recreate the container in place
• clean.sh: remove the container, image, and persisted agent data

Common examples:

sudo ./update.sh
sudo ./update.sh --image-tag 0.04.16.26.4
sudo ./update.sh --use-bundle-tag
sudo ./clean.sh --yes

update.sh defaults to Docker Hub latest. If you want to stay on the bundle's pinned release, use --use-bundle-tag.

clean.sh --yes is the reset-to-zero path. It removes the container and the persisted data configured in .env, so the next install.sh run starts with a fresh Synology directory tree.

Treat install.sh, update.sh, and clean.sh as privileged commands. Run sudo -v first and stop immediately if authentication fails.

⁠Step 5: Verify The Install

Once the container is running, open the browser UI:

• http://<nas-host>:42588/api/ui

Check readiness:

• curl http://<nas-host>:42588/api/openapi.json

Check the current identity from inside the container:

sudo docker exec hyperspace-service /bin/bash -lc 'HS_IDENTITY_URL="http://127.0.0.1:42587/api/command/whoAmI" /usr/local/bin/extractIdentityValue.sh'

⁠What To Expect After Setup

• The container name will be hyperspace-service.
• The REST API will listen on host port 42588.
• Persistent state will be mounted at /var/lib/hyperspace.
• Logs will be mounted at /var/log/hyperspace.
• The local-only management port will bind to 127.0.0.1:8421.
• The working directory on the NAS will be /volume1/HyperSpaceServiceAgent unless you chose a different HS_ROOT.

⁠If The Container Exits Immediately

The most common cause is a missing TUN device on the NAS host.

From the NAS shell, check:

ls -l /dev/net/tun

If the device is missing, rerun the setup from a root shell. If Synology still does not allow install.sh to create it, prepare /dev/net/tun on the host first and then rerun sudo ./install.sh.

If install.sh fails with a Docker permission error, stop and validate sudo -v again before retrying.

If install.sh fails with a port binding error, another container is already using one of the host ports. Edit .env in the extracted bundle, then rerun sudo ./install.sh.

⁠Choose The Right HyperSpace Image

• whitestarcommunications/synology-hyperspaceconnectionagent Create secure outbound HyperSpace connections from this device.
• whitestarcommunications/synology-hyperspaceproxyagent Accept secure inbound HyperSpace traffic and relay it to local services.
• whitestarcommunications/synology-hyperspaceserviceagent Expose services securely through HyperSpace.