Launch Configuration¶
Environment Variables¶
Environment variables are used to configure the Helios container. The following environment variables are available:
| Name | Value | Required |
|---|---|---|
| USER | Name of the user | X |
| UID | POSIX compliant uid for the user | X |
| GID | POSIX compliant gid for the user | |
| PASSWORD | Password set for the user. Required for DCV native client direct-connect (port 8443) | |
| IDLE_TIME | Trigger the idle hook after x minutes. Previously used by the auto shutdown plugin, which is deprecated as of Genesis v5.2.0 / Orion Workspaces v4.3.0 in favor of Orion's built-in auto shutdown / auto hibernate |
|
| DISABLE_VGL | Disable VirtualGL Wrapper around the entire desktop session. Set to false to use vglrun (default: false, vglrun enabled). Set to true (or any value) to run without vglrun. Matches the pattern of DISABLE_ZINK. |
|
| DISABLE_ZINK | Disable ZINK acceleration. Set to false to enable ZINK (default: true, ZINK disabled). Set to true (or any value) to disable ZINK. Matches the pattern of DISABLE_VGL. |
|
| DESKTOP_FILES | Paths separated by :. For example, /some/path/1/*.desktop:/some/*/2/*.desktop |
|
| PREFIX | Prefix for URL for use behind a reverse proxy, both slashes required, e.g. /custom/prefix/ |
|
| SELKIES_FRAMERATE | Set framerate as a range (e.g., 15-60) or a fixed value (e.g., 30) |
|
| SUDO | Grant SUDO to the user on the container ("true" or "1") |
|
| REMOTE_PROTOCOL | Remote desktop protocol: selkies (default) or dcv |
|
| DCV_LICENSE_FILE | Path to a DCV license file for non-EC2 usage. Falls back to auto-license on EC2 or 30-day demo otherwise. | |
| DCV_DIRECT_PORT | Port for the DCV native client direct-connect endpoint. Default 8443. Requires PASSWORD to be set. |
Endpoints¶
Helios provides the following endpoints for accessing the desktop:
Selkies mode (REMOTE_PROTOCOL=selkies)¶
| Endpoint | Description |
|---|---|
{PREFIX}/ |
Web-based desktop (port 3000) |
DCV mode (REMOTE_PROTOCOL=dcv)¶
| Endpoint | Description |
|---|---|
{PREFIX}/ |
Web-based desktop via browser (port 3000, no auth) |
<host>:<DCV_DIRECT_PORT> |
Native DCV client direct-connect (port 8443, PAM auth via PASSWORD) |
The DCV direct-connect endpoint uses both TCP and QUIC (UDP) for lower-latency streaming.
Connect using the DCV native client
with the address <host>:<DCV_DIRECT_PORT> and username <USER>.
Ports¶
Helios exposes the following ports:
| Port | Protocol | Description |
|---|---|---|
| 3000 | TCP | HTTPS Desktop (Selkies or DCV) |
| 8443 | TCP+UDP | DCV native client direct-connect (when REMOTE_PROTOCOL=dcv and PASSWORD is set) |
Remote Protocols¶
Selkies (default)¶
Selkies is a WebRTC-based remote desktop protocol. It provides a web-based client that works in any modern browser without additional software. Selkies is the default and recommended protocol for browser-based access.
DCV¶
Amazon DCV (NICE DCV) is an alternative remote desktop protocol that supports both web browser and native client access.
DCV key characteristics:
- Console sessions only — DCV connects to the same Xvfb display as Selkies. Both protocols show the same desktop.
- Web access — Served on port 3000 behind nginx, same as Selkies. The web endpoint is unauthenticated.
- Native client — A separate dcvserver instance on port 8443 provides
password-authenticated access for the DCV native client.
Requires
PASSWORDto be set. - iframe embedding — DCV web client supports iframe embedding from any origin (CORS
headers are set,
X-Frame-Optionsis stripped). - No GPU sharing — DCV-GL is installed but the console session does not use it. GPU acceleration is handled by VirtualGL (same as Selkies).
DCV Licensing
DCV requires a license. Helios handles licensing automatically:
- On EC2 uses the free built-in EC2 license.
- Without a license starts a 30-day demo license on first run.
- BYOL set
DCV_LICENSE_FILEto the path of your license file.
The demo license is generated at container start via the DCV package postinst script. This ensures each container gets its own valid license state.
EC2 IMDS Hop Limit
On EC2, DCV fetches its free license from the Instance Metadata Service
(IMDS) at 169.254.169.254. Containers in a separate network namespace
(bridge/overlay) add one extra hop. The default IMDS hop limit of 1
drops their requests, causing DCV license checkout to fail.
Host networking (--network host) — no extra hop. Default hop limit
works. No change needed.
-
Bridge/overlay/EKS/Fargate — IMDS needs hop limit ≥ 2:
-
Karpenter — add to
EC2NodeClass.spec.metadataOptions: - EKS managed node groups / launch templates — set
MetadataOptions.HttpPutResponseHopLimitto2. - Plain Docker / ECS EC2 — apply to the instance:
DCV Audio
DCV uses the same PulseAudio null-sink setup as Selkies. Desktop audio is captured
from the output monitor and streamed to the client. Microphone input arrives via
the DCV agent's virtual microphone (AWS-Virtual-Microphone).
GPU Acceleration Configuration¶
Running Without a GPU¶
Helios can be run without a physical GPU. The default configuration has DISABLE_VGL=false (vglrun enabled), which allows the desktop to start via VirtualGL's software rendering path (llvpipe). This is the out-of-the-box experience for cloud/deployments without GPU hardware. If you have no GPU and experience issues, verify your container has access to /dev/dri devices.
Running With ZINK¶
Set DISABLE_ZINK=false to enable ZINK acceleration. ZINK is an OpenGL implementation that runs over Vulkan and is particularly useful:
- AMD GPUs with open-source drivers that support Vulkan but have limited native OpenGL support
- Compatibility scenarios where applications expect OpenGL but the backend is Vulkan-based
- Container environments where direct driver access is restricted
Warning
ZINK may add overhead for some workloads. The default is DISABLE_ZINK=true (ZINK disabled).
3D Heavy Applications (Houdini, Maya, etc.)¶
For professional 3D applications with a discrete GPU, you may experience performance issues if VGL or ZINK are enabled. Both add translation overhead:
Warning
- VGL adds host-side VirtualGL translation
- ZINK adds OpenGL-to-Vulkan translation
For best performance with Houdini, Maya, or similar applications:
- Set
DISABLE_VGL=trueto disable the VGL wrapper - Set
DISABLE_ZINK=trueto disable ZINK acceleration
When disabling both features and using native GPU drivers, you will also need to proper ICD (Installable Client Driver) files so OpenGL can discover the correct GPU driver (see "ICD Files for Target GPU" below).
ICD Files for Target GPU¶
When using native GPU drivers (both VGL and ZINK disabled), you need to provide ICD (Installable Client Driver) configuration so the OpenGL stack can find the correct driver library.
NVIDIA ICD example (nvidia.json):
ICD file placement:
- /etc/ld.so.d/ — for library linker discovery (example above)
- /usr/share/glvnd/egl/vendor.d/ — preferred for modern GLVND implementations
Deployment method examples:
Docker run:
docker run -v /path/to/nvidia.json:/etc/ld.so.d/nvidia.json \
-e DISABLE_VGL=true -e DISABLE_ZINK=true \
junoinnovations/helios:unstable-jammy
Docker Compose:
services:
helios:
image: junoinnovations/helios:unstable-jammy
volumes:
- ./nvidia.json:/etc/ld.so.d/nvidia.json
environment:
- DISABLE_VGL=true
- DISABLE_ZINK=true
Kubernetes:
apiVersion: apps/v1
kind: Deployment
metadata:
name: helios
spec:
template:
spec:
containers:
- name: helios
image: junoinnovations/helios:unstable-jammy
volumeMounts:
- name: nvidia-icd
mountPath: /etc/ld.so.d
volumes:
- name: nvidia-icd
configMap:
name: nvidia-icd-config
When using REMOTE_PROTOCOL=selkies (the default), many of the environment variables provided by the upstream Selkies project will be respected.
You can find official Selkies documentation here: https://selkies-project.github.io/selkies/usage/#command-line-options-and-environment-variables
Info
The GID will match the UID if not specified.
UID and GID
The UID and GID are NOT the user that is launching and running the container.
Because of s6, the container always starts and runs as root. It then uses s6 to run the desktop using the specified
user using those environment variables. This is done to ensure that the desktop has the correct permissions and
ownership on things like the home directory and other files. This helps with things like Network Shares as well.
Authentication
When using REMOTE_PROTOCOL=selkies, Helios DOES NOT provide any authentication for the web endpoint. This means that anyone who can
connect to the http endpoint can access the desktop as that user. For proper security, we recommend using a
reverse proxy with authentication in front of Helios. This can be done using Nginx, Traefik, or any other
reverse proxy that supports authentication.
When using REMOTE_PROTOCOL=dcv, the web endpoint (port 3000) is also unauthenticated. However, setting PASSWORD
enables a separate password-authenticated endpoint on port 8443 for native DCV clients. The web endpoint remains
open — use a reverse proxy for access control.
Security is a very important part of any deployment and it isn't a one size fits all solution. Instead of shipping Helios with a specific authentication method, we leave it up to the user to implement their own security measures that best fit their deployment. This allows for more flexibility and customization in how Helios is used.
When using the Orion Platform, Authentication and authorization is handled by the product, ensuring the security of your deployment.