whitestarcommunications/hyperspaceserviceagent repository overview

⁠HyperSpace Service Agent

Primary HyperSpace service workload with REST and CLI endpoints.

⁠When To Use This Image

Expose services securely through HyperSpace.

This is the standalone Linux Docker image for HyperSpace Service Agent. Use it when you want to run the agent directly on a Linux Docker host and keep its state in Docker volumes or bind mounts.

Repository: whitestarcommunications/hyperspaceserviceagent

Current release tag:

• 0.04.15.26.2

If you are writing automation, pin the image to:

• whitestarcommunications/hyperspaceserviceagent:0.04.15.26.2

⁠Before You Start

This image expects a Linux Docker host that can expose /dev/net/tun to the container. It is not intended for clicking Run in Docker Desktop on macOS or Windows.

The container also needs:

• NET_ADMIN
• NET_RAW
• persistent storage for state, logs, and runtime files

⁠Quick Start

The following example creates three named volumes, then starts the agent with the TUN device and the required capabilities.

docker volume create hyperspace-service-state
docker volume create hyperspace-service-log
docker volume create hyperspace-service-data

docker run -d \
  --name hyperspace-service \
  --restart unless-stopped \
  --cap-drop ALL \
  --cap-add NET_ADMIN \
  --cap-add NET_RAW \
  --security-opt no-new-privileges:true \
  --device /dev/net/tun:/dev/net/tun \
  -e HS_STATUS_WEB_ENABLED=true \
  -e HS_STATUS_LIVE_REFRESH_ENABLED=true \
  -p 127.0.0.1:42588:42587 \
  -p 127.0.0.1:8420:8420 \
  -v hyperspace-service-state:/var/lib/hyperspace \
  -v hyperspace-service-log:/var/log/hyperspace \
  -v hyperspace-service-data:/root/serviceAgent \
  whitestarcommunications/hyperspaceserviceagent:0.04.15.26.2

⁠What Those Volumes Are For

• /var/lib/hyperspace: long-lived identity and runtime state
• /var/log/hyperspace: logs written by the agent
• /root/serviceAgent: profile-specific working data

On first startup the container writes a readable onboarding summary under:

• /var/lib/hyperspace/HyperSpaceSupport/OnboardingSummary.txt

Those volumes are what preserve the agent state when you replace the container with a newer image tag.

⁠Verify The Agent

The fastest checks are:

• status page: http://127.0.0.1:8420/
• readiness: curl http://127.0.0.1:42588/api/openapi.json
• browser UI: http://127.0.0.1:42588/api/ui

To print the current identity from inside the running container:

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

⁠Update Safely

To move to a newer image:

1. Pull the new tag.
2. Stop and remove the old container.
3. Start a new container with the same mounted volumes.

The image can change. The mounted state should not.

⁠Docker Desktop Note

If you are on macOS or Windows, use the Kubernetes install path from this repository instead of trying to run this image directly in Docker Desktop. The standalone container cannot enable /dev/net/tun for itself.

The usual local command is:

./install-docker-desktop-agent.sh service

⁠Choose The Right HyperSpace Image

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