Overview

This guide walks through setting up Chameleon in the cloud from scratch on either AWS or OCI. First-time setup is typically ~15–25 minutes; subsequent starts are typically ~2–3 minutes.

What You’ll Accomplish

• ✅ Cloud GPU instance running Chameleon
• ✅ Remote desktop access via browser (noVNC)
• ✅ Full GPU acceleration (via Vulkan drivers for SPIR-V)
• ✅ Automated startup/shutdown scripts
• ✅ Ability to demo to customers/partners

Prerequisites

Get the Chameleon binary

You can download the pilot binary directly, or we can provide it as part of the on-prem pilot package/runbook depending on your environment.

Get the AWS and OCI startup scripts

Use the script that matches your cloud provider. These scripts prepare the remote session environment and start required services.

SSH Key Handling (Important)

Pilot access relies on SSH key authentication. If you are switching machines (desktop → laptop), ensure the correct private key is present on the machine you are using.

Verify your key exists

ls -l ~/.ssh

Copy a key from another machine (example)

scp user@OTHER_MACHINE_IP:~/.ssh/pilot-key ~/.ssh/

Note: If you cannot ping or SSH between machines on the same LAN, verify firewall settings and that “Remote Login” is enabled on macOS.

How to Participate in the Chameleon Pilot

Quick Reference

cd ~/chameleon && ./chameleon_start.sh start
cd ~/chameleon && ./chameleon_start.sh stop
cd ~/chameleon && ./chameleon_start.sh restart
cd ~/chameleon && ./chameleon_start.sh status
cd ~/chameleon && ./chameleon_start.sh logs
cd ~/chameleon && ./chameleon_start.sh test

This startup script is designed for AWS NVIDIA GPU instances
running Ubuntu 24.04 with browser-based access via
noVNC and full GPU acceleration using Vulkan (SPIR-V).

The script manages:

• Virtual X server (Xvfb)
• VNC server (x11vnc)
• Browser access (noVNC + websockify)
• PulseAudio
• NVIDIA Vulkan ICD setup
• Chameleon lifecycle (start / stop / status / logs / test)

Create the Startup Script

Run the following commands on your AWS instance to create the startup script:

cd ~/chameleon
cat > chameleon_start.sh << 'ENDOFSCRIPT'
#!/usr/bin/env bash
set -euo pipefail

# ===================== Config =====================
DISPLAY_NUMBER="${DISPLAY_NUMBER:-99}"
export DISPLAY=":${DISPLAY_NUMBER}"

X_RES="${X_RES:-1920}"
X_HI="${X_HI:-1080}"
X_DEPTH="${X_DEPTH:-24}"

VNC_PORT="${VNC_PORT:-5901}"
NOVNC_PORT="${NOVNC_PORT:-6080}"

CHAMELEON_BIN="${CHAMELEON_BIN:-$HOME/chameleon/Essence__LNX_X64.w.elf}"
WORKDIR="${WORKDIR:-$HOME/chameleon}"
LOGDIR="${LOGDIR:-$HOME/.local/state/chameleon/Log}"

mkdir -p "$LOGDIR"

export VK_ICD_FILENAMES="/usr/share/vulkan/icd.d/nvidia_icd.json"
export SDL_AUDIODRIVER=pulse

# ===================== Functions =====================

install_deps() {
  echo "[install] Installing dependencies..."
  sudo apt-get update
  sudo apt-get install -y \
    xvfb \
    x11vnc \
    websockify \
    novnc \
    vulkan-tools \
    mesa-vulkan-drivers \
    pulseaudio \
    nvidia-utils-550 \
    libnvidia-gl-550

  if [ ! -f /usr/share/vulkan/icd.d/nvidia_icd.json ]; then
    sudo mkdir -p /usr/share/vulkan/icd.d/
    sudo bash -c 'cat > /usr/share/vulkan/icd.d/nvidia_icd.json << EOF
{
  "file_format_version" : "1.0.0",
  "ICD": {
    "library_path": "libGLX_nvidia.so.0",
    "api_version" : "1.3.275"
  }
}
EOF'
  fi
}

clean_locks() {
  sudo rm -f /tmp/.X${DISPLAY_NUMBER}-lock
  sudo rm -f /tmp/.X11-unix/X${DISPLAY_NUMBER}
}

start_pulseaudio() {
  pulseaudio --check && pulseaudio --kill || true
  pulseaudio --start >"$LOGDIR/pulseaudio.log" 2>&1
}

start_xvfb() {
  Xvfb "${DISPLAY}" -screen 0 "${X_RES}x${X_HI}x${X_DEPTH}" \
    -ac +extension GLX +render -noreset \
    >"$LOGDIR/xvfb.log" 2>&1 &
  sleep 2
}

start_vnc() {
  pkill -f "x11vnc.*${VNC_PORT}" 2>/dev/null || true
  x11vnc -display "${DISPLAY}" -rfbport "${VNC_PORT}" \
    -forever -shared -nopw \
    >"$LOGDIR/vnc.log" 2>&1 &
}

start_websockify() {
  pkill -f "websockify.*${NOVNC_PORT}" 2>/dev/null || true
  websockify --web=/usr/share/novnc/ \
    "${NOVNC_PORT}" "localhost:${VNC_PORT}" \
    >"$LOGDIR/websockify.log" 2>&1 &
}

start_chameleon() {
  chmod +x "$CHAMELEON_BIN"
  cd "$WORKDIR"
  DISPLAY="${DISPLAY}" \
  VK_ICD_FILENAMES="${VK_ICD_FILENAMES}" \
  SDL_AUDIODRIVER="${SDL_AUDIODRIVER}" \
  "$CHAMELEON_BIN" >"$LOGDIR/chameleon.log" 2>&1 &
}

case "${1:-start}" in
  install) install_deps ;;
  start)
    clean_locks
    start_pulseaudio
    start_xvfb
    start_vnc
    start_websockify
    start_chameleon
    ;;
  stop)
    pkill -f Xvfb || true
    pkill -f x11vnc || true
    pkill -f websockify || true
    pkill -f Essence || true
    pulseaudio --kill || true
    clean_locks
    ;;
  restart)
    "$0" stop
    sleep 2
    "$0" start
    ;;
  status)
    pgrep -fa Essence || echo "Chameleon not running"
    ;;
  logs)
    tail -f "$LOGDIR"/*.log
    ;;
  test)
    nvidia-smi
    DISPLAY="${DISPLAY}" vulkaninfo --summary | head -20
    ;;
  *)
    echo "Usage: $0 {install|start|stop|restart|status|logs|test}"
    ;;
esac
ENDOFSCRIPT

chmod +x chameleon_start.sh

Next Steps

• Run ./chameleon_start.sh install once
• Upload Essence__LNX_X64.w.elf to ~/chameleon
• Start Chameleon with ./chameleon_start.sh start
• Access UI via http://localhost:6080/vnc.html

Note: This script is AWS-specific. OCI uses a different driver,
networking, and image model and requires a separate startup script.

This startup script is designed for OCI NVIDIA GPU instances
running Ubuntu 24.04 with browser-based access via noVNC
and full GPU acceleration via Vulkan (SPIR-V).

It manages: Xvfb (virtual display), x11vnc,
noVNC/websockify, PulseAudio, and the
Chameleon binary lifecycle (start/stop/status/logs/test).

Ports & Networking (OCI Reminder)

• SSH: 22 (source: your IP)
• noVNC: 6080 (source: your IP)
• OCI often requires allowing these in both NSG/Security List and host firewall (if enabled).

Create the Startup Script (OCI)

Run this on the OCI instance:

cd ~/chameleon
cat > chameleon_start_oci.sh << 'ENDOFSCRIPT'
#!/usr/bin/env bash
set -euo pipefail

# ===================== Config =====================
DISPLAY_NUMBER="${DISPLAY_NUMBER:-99}"
export DISPLAY=":${DISPLAY_NUMBER}"

X_RES="${X_RES:-1920}"
X_HI="${X_HI:-1080}"
X_DEPTH="${X_DEPTH:-24}"

VNC_PORT="${VNC_PORT:-5901}"
NOVNC_PORT="${NOVNC_PORT:-6080}"

CHAMELEON_BIN="${CHAMELEON_BIN:-$HOME/chameleon/Essence__LNX_X64.w.elf}"
WORKDIR="${WORKDIR:-$HOME/chameleon}"
LOGDIR="${LOGDIR:-$HOME/.local/state/chameleon/Log}"

mkdir -p "$LOGDIR"

# Vulkan + audio defaults
export SDL_AUDIODRIVER=pulse

# NOTE: NVIDIA ICD path varies slightly by image/driver package.
# We'll set it if we find it; otherwise vulkaninfo will reveal what's present.
set_vk_icd() {
  if [ -f /usr/share/vulkan/icd.d/nvidia_icd.json ]; then
    export VK_ICD_FILENAMES="/usr/share/vulkan/icd.d/nvidia_icd.json"
  elif [ -f /etc/vulkan/icd.d/nvidia_icd.json ]; then
    export VK_ICD_FILENAMES="/etc/vulkan/icd.d/nvidia_icd.json"
  fi
}

# ===================== Functions =====================

install_base_deps() {
  echo "[install] Installing base deps (Xvfb/VNC/noVNC/Vulkan tools)..."
  sudo apt-get update
  sudo apt-get install -y \
    xvfb \
    x11vnc \
    websockify \
    novnc \
    pulseaudio \
    vulkan-tools \
    mesa-vulkan-drivers \
    ubuntu-drivers-common \
    ca-certificates \
    curl \
    unzip
}

ensure_nvidia_driver() {
  echo "[install] Ensuring NVIDIA driver is present..."
  if command -v nvidia-smi >/dev/null 2>&1; then
    echo "[install] nvidia-smi found (driver likely installed)."
    nvidia-smi || true
    return 0
  fi

  echo "[install] nvidia-smi NOT found. Attempting driver install via ubuntu-drivers..."
  sudo ubuntu-drivers autoinstall

  echo "[install] Driver install complete. Reboot is required."
  echo ">>> Run: sudo reboot"
  exit 0
}

ensure_vulkan_nvidia_icd_hint() {
  # In most Ubuntu NVIDIA driver installs, the ICD file exists already.
  # This is a safety hint only, not a hard override.
  if [ -f /usr/share/vulkan/icd.d/nvidia_icd.json ] || [ -f /etc/vulkan/icd.d/nvidia_icd.json ]; then
    echo "[install] NVIDIA Vulkan ICD JSON present."
    return 0
  fi

  echo "[install] WARNING: NVIDIA Vulkan ICD JSON not found in common locations."
  echo "[install] vulkaninfo will help diagnose. Continuing."
}

clean_locks() {
  sudo rm -f /tmp/.X${DISPLAY_NUMBER}-lock
  sudo rm -f /tmp/.X11-unix/X${DISPLAY_NUMBER}
}

start_pulseaudio() {
  pulseaudio --check && pulseaudio --kill || true
  pulseaudio --start >"$LOGDIR/pulseaudio.log" 2>&1
}

start_xvfb() {
  Xvfb "${DISPLAY}" -screen 0 "${X_RES}x${X_HI}x${X_DEPTH}" \
    -ac +extension GLX +render -noreset \
    >"$LOGDIR/xvfb.log" 2>&1 &
  sleep 2
}

start_vnc() {
  pkill -f "x11vnc.*${VNC_PORT}" 2>/dev/null || true
  x11vnc -display "${DISPLAY}" -rfbport "${VNC_PORT}" \
    -forever -shared -nopw \
    >"$LOGDIR/vnc.log" 2>&1 &
}

start_websockify() {
  pkill -f "websockify.*${NOVNC_PORT}" 2>/dev/null || true
  websockify --web=/usr/share/novnc/ \
    "${NOVNC_PORT}" "localhost:${VNC_PORT}" \
    >"$LOGDIR/websockify.log" 2>&1 &
}

start_chameleon() {
  if [ ! -f "$CHAMELEON_BIN" ]; then
    echo "[start] ERROR: Chameleon binary not found at: $CHAMELEON_BIN"
    echo "Place it at: $HOME/chameleon/Essence__LNX_X64.w.elf (or set CHAMELEON_BIN env var)"
    exit 1
  fi

  chmod +x "$CHAMELEON_BIN"
  cd "$WORKDIR"

  set_vk_icd

  DISPLAY="${DISPLAY}" \
  ${VK_ICD_FILENAMES:+VK_ICD_FILENAMES="${VK_ICD_FILENAMES}"} \
  SDL_AUDIODRIVER="${SDL_AUDIODRIVER}" \
  "$CHAMELEON_BIN" >"$LOGDIR/chameleon.log" 2>&1 &
}

stop_all() {
  pkill -f Xvfb || true
  pkill -f x11vnc || true
  pkill -f websockify || true
  pkill -f Essence__LNX_X64 || true
  pkill -f Essence || true
  pulseaudio --kill || true
  clean_locks
}

case "${1:-start}" in
  install)
    install_base_deps
    ensure_nvidia_driver
    ensure_vulkan_nvidia_icd_hint
    echo "[install] OK. Now upload the Chameleon binary, then run: ./chameleon_start_oci.sh start"
    ;;
  start)
    clean_locks
    start_pulseaudio
    start_xvfb
    start_vnc
    start_websockify
    start_chameleon
    echo "[start] noVNC listening on port ${NOVNC_PORT}"
    ;;
  stop)
    stop_all
    ;;
  restart)
    stop_all
    sleep 2
    "$0" start
    ;;
  status)
    pgrep -fa Xvfb || echo "Xvfb not running"
    pgrep -fa x11vnc || echo "x11vnc not running"
    pgrep -fa websockify || echo "websockify not running"
    pgrep -fa Essence || echo "Chameleon not running"
    ;;
  logs)
    tail -f "$LOGDIR"/*.log
    ;;
  test)
    echo "=== nvidia-smi ==="
    nvidia-smi || true
    echo
    echo "=== vulkaninfo (summary) ==="
    set_vk_icd
    ${VK_ICD_FILENAMES:+VK_ICD_FILENAMES="${VK_ICD_FILENAMES}"} vulkaninfo --summary | head -40 || true
    ;;
  *)
    echo "Usage: $0 {install|start|stop|restart|status|logs|test}"
    ;;
esac
ENDOFSCRIPT

chmod +x chameleon_start_oci.sh

How to Use

• One-time install: ./chameleon_start_oci.sh install (may trigger a reboot if drivers are installed)
• Upload binary: put Essence__LNX_X64.w.elf in ~/chameleon/
• Start: ./chameleon_start_oci.sh start
• Test: ./chameleon_start_oci.sh test

Connect via noVNC

SSH tunnel (recommended):

ssh -L 6080:localhost:6080 -i /path/to/your-oci-key ubuntu@YOUR_OCI_PUBLIC_IP

Browser:

http://localhost:6080/vnc.html

Note: OCI images and GPU driver packaging vary by region/shape. If install installs drivers, it will exit and require a reboot.
After reboot, run ./chameleon_start_oci.sh install again (it will be fast) and then start.

What the on-prem pilot validates (Phase 1)

• Built-in workloads: We provide the workloads used for the pilot. No workload integration is required for Phase 1.
• Single-GPU testing: If your server has multiple GPUs, the pilot targets one GPU per run.
• Multi-GPU modules: For example, an NVIDIA A100/H100 module may have 8 GPUs; we validate by running the pilot on one GPU at a time.
• What you get: A repeatable baseline vs. optimized comparison for the tested GPU, plus logs/results for review.

GPU targets and driver expectations

• NVIDIA: Supported via NVIDIA driver stack + Vulkan support for the SPIR-V execution path.
• AMD: Supported via AMD GPU driver stack + Vulkan (RADV/AMDGPU where applicable) for SPIR-V execution. We’ll confirm the best known-good path for your distro/driver.

Headless mode (recommended for secure labs)

Get the Chameleon binary

You can download the pilot binary directly, or we can provide it directly via the most convenient method. Contact to us by clicking on the button below.

Get the on-prem startup scripts

What happens next

• Step 1: Share your target hardware and OS (GPU model, driver version, Linux distro).
• Step 2: We provide an on-prem pilot package consisting of the Chameleon binary, startup scripts, and this on-prem pilot guide, which serves as the execution runbook for Phase 1 validation.
• Step 3: You run the pilot on a chosen GPU and capture the results.
• Step 4: We review results together and discuss what multi-GPU and multi-node expansion would require.
• Step 5: We work together to produce a results report covering performance, energy, utilization, and recommended next steps.

This script runs Chameleon in true headless mode (no VNC/noVNC). It creates a dummy X display only if required for Vulkan/SDL rendering.
This is the most stable mode for secure labs and data centers.

Create the script

cd ~/chameleon
cat > chameleon_start_onprem_headless.sh << 'ENDOFSCRIPT'
#!/usr/bin/env bash
set -euo pipefail

DISPLAY_NUMBER="${DISPLAY_NUMBER:-99}"
export DISPLAY=":${DISPLAY_NUMBER}"

X_RES="${X_RES:-1920}"
X_HI="${X_HI:-1080}"
X_DEPTH="${X_DEPTH:-24}"

CHAMELEON_BIN="${CHAMELEON_BIN:-$HOME/chameleon/Essence__LNX_X64.w.elf}"
WORKDIR="${WORKDIR:-$HOME/chameleon}"
LOGDIR="${LOGDIR:-$HOME/.local/state/chameleon/Log}"

mkdir -p "$LOGDIR"

clean_locks() {
  sudo rm -f /tmp/.X${DISPLAY_NUMBER}-lock
  sudo rm -f /tmp/.X11-unix/X${DISPLAY_NUMBER}
}

start_xvfb() {
  # Dummy display only — no remote visualization
  Xvfb "${DISPLAY}" -screen 0 "${X_RES}x${X_HI}x${X_DEPTH}" \
    -ac +extension GLX +render -noreset \
    >"$LOGDIR/xvfb.log" 2>&1 &
  sleep 2
}

start_chameleon() {
  if [ ! -f "$CHAMELEON_BIN" ]; then
    echo "[start] ERROR: Chameleon binary not found at: $CHAMELEON_BIN"
    exit 1
  fi
  chmod +x "$CHAMELEON_BIN"
  cd "$WORKDIR"
  DISPLAY="${DISPLAY}" "$CHAMELEON_BIN" >"$LOGDIR/chameleon.log" 2>&1 &
}

stop_all() {
  pkill -f Xvfb || true
  pkill -f Essence__LNX_X64 || true
  pkill -f Essence || true
  clean_locks
}

case "${1:-start}" in
  start)
    clean_locks
    start_xvfb
    start_chameleon
    echo "[start] Headless mode running (no VNC). Logs: $LOGDIR"
    ;;
  stop)
    stop_all
    ;;
  restart)
    stop_all
    sleep 2
    "$0" start
    ;;
  status)
    pgrep -fa Xvfb || echo "Xvfb not running"
    pgrep -fa Essence || echo "Chameleon not running"
    ;;
  logs)
    tail -f "$LOGDIR"/*.log
    ;;
  *)
    echo "Usage: $0 {start|stop|restart|status|logs}"
    ;;
esac
ENDOFSCRIPT

chmod +x chameleon_start_onprem_headless.sh

Run it

./chameleon_start_onprem_headless.sh start
./chameleon_start_onprem_headless.sh status
./chameleon_start_onprem_headless.sh logs

Note: If your environment already provides a valid display/rendering path, you can remove Xvfb and run the binary directly. Keep headless as the default to avoid session-lifecycle instability.

Use this only if you need a remote desktop view. It starts Xvfb + x11vnc + noVNC. Interactive sessions can introduce lifecycle issues in some environments, so headless is preferred for validation.

Create the script

cd ~/chameleon
cat > chameleon_start_onprem_interactive.sh << 'ENDOFSCRIPT'
#!/usr/bin/env bash
set -euo pipefail

DISPLAY_NUMBER="${DISPLAY_NUMBER:-99}"
export DISPLAY=":${DISPLAY_NUMBER}"

X_RES="${X_RES:-1920}"
X_HI="${X_HI:-1080}"
X_DEPTH="${X_DEPTH:-24}"

VNC_PORT="${VNC_PORT:-5901}"
NOVNC_PORT="${NOVNC_PORT:-6080}"

CHAMELEON_BIN="${CHAMELEON_BIN:-$HOME/chameleon/Essence__LNX_X64.w.elf}"
WORKDIR="${WORKDIR:-$HOME/chameleon}"
LOGDIR="${LOGDIR:-$HOME/.local/state/chameleon/Log}"

mkdir -p "$LOGDIR"

clean_locks() {
  sudo rm -f /tmp/.X${DISPLAY_NUMBER}-lock
  sudo rm -f /tmp/.X11-unix/X${DISPLAY_NUMBER}
}

start_xvfb() {
  Xvfb "${DISPLAY}" -screen 0 "${X_RES}x${X_HI}x${X_DEPTH}" \
    -ac +extension GLX +render -noreset \
    >"$LOGDIR/xvfb.log" 2>&1 &
  sleep 2
}

start_vnc() {
  pkill -f "x11vnc.*${VNC_PORT}" 2>/dev/null || true
  x11vnc -display "${DISPLAY}" -rfbport "${VNC_PORT}" \
    -forever -shared -nopw \
    >"$LOGDIR/vnc.log" 2>&1 &
}

start_websockify() {
  pkill -f "websockify.*${NOVNC_PORT}" 2>/dev/null || true
  websockify --web=/usr/share/novnc/ \
    "${NOVNC_PORT}" "localhost:${VNC_PORT}" \
    >"$LOGDIR/websockify.log" 2>&1 &
}

start_chameleon() {
  if [ ! -f "$CHAMELEON_BIN" ]; then
    echo "[start] ERROR: Chameleon binary not found at: $CHAMELEON_BIN"
    exit 1
  fi
  chmod +x "$CHAMELEON_BIN"
  cd "$WORKDIR"
  DISPLAY="${DISPLAY}" "$CHAMELEON_BIN" >"$LOGDIR/chameleon.log" 2>&1 &
}

stop_all() {
  pkill -f Xvfb || true
  pkill -f x11vnc || true
  pkill -f websockify || true
  pkill -f Essence__LNX_X64 || true
  pkill -f Essence || true
  clean_locks
}

case "${1:-start}" in
  start)
    clean_locks
    start_xvfb
    start_vnc
    start_websockify
    start_chameleon
    echo "[start] noVNC on port ${NOVNC_PORT}"
    ;;
  stop)
    stop_all
    ;;
  restart)
    stop_all
    sleep 2
    "$0" start
    ;;
  status)
    pgrep -fa Xvfb || echo "Xvfb not running"
    pgrep -fa x11vnc || echo "x11vnc not running"
    pgrep -fa websockify || echo "websockify not running"
    pgrep -fa Essence || echo "Chameleon not running"
    ;;
  logs)
    tail -f "$LOGDIR"/*.log
    ;;
  *)
    echo "Usage: $0 {start|stop|restart|status|logs}"
    ;;
esac
ENDOFSCRIPT

chmod +x chameleon_start_onprem_interactive.sh

Connect (noVNC)

ssh -L 6080:localhost:6080 user@YOUR_ONPREM_HOST
http://localhost:6080/vnc.html

Note: Keep access restricted (source IP / VPN / bastion). If you don’t need interactive viewing, use the headless script instead.

Minimum configuration

• OS (pilot-certified): Ubuntu 24.04.
• OS (platform capability): Designed for 50+ Linux distros; tested on 30+; runs without modifications.
• CPU: Modern x86_64 (Intel/AMD). 4+ cores recommended.
• Memory: 16 GB minimum (32 GB recommended).
• Storage: 20 GB free minimum (50+ GB recommended for repeat runs and logs).
• GPU: At least one supported GPU.
• GPU stack: Driver + Vulkan support required (SPIR-V execution path).

Recommended configuration

• CPU: 8–32 cores.
• Memory: 32–64 GB.
• Storage: NVMe SSD recommended.
• GPU: A modern NVIDIA GPU is recommended for the current pilot path. Additional GPU architectures are being evaluated.
• OS: Ubuntu 24.04 recommended for the smoothest “known-good” pilot path.

High-spec environments

• Multi-GPU servers: Supported for access and evaluation, but pilot validation runs are executed on one GPU at a time.
• Examples: NVIDIA T4/A10/A100/H100, AMD Instinct MI100/MI200, Radeon Pro class platforms, and dense AI servers.