Environment variable reference

Set variables in the Caller process before the first graft call. Hypertube caches runtime context after initialization; restart the process after changes.

Gateway

Treat GC_PROJECT_KEY as a secret. GG_DEBUG can expose invocation data and should remain off during normal production operation.

Generated Graft configuration sources

Generated packages resolve configuration from environment pointers and files. The environment variable does not hold graft settings directly — it points to inline JSON/YAML, a file path, or a connection string.

Keys inside the resolved configuration include host, modules, runtime, stateless, licenseKey, and per-runtime channel.runtimePath. See Configuration keys and precedence.

Environment pointers outrank files, programmatic configuration, and generated defaults.

Hypertube activation

Resolution order: licenseKey from configuration file, then HYPERTUBE_KEY environment variable, then license file on disk.

Embedded Receiver runtime paths (in-memory)

When host=inmemory and the Caller technology differs from the Receiver technology, Hypertube must load the Receiver's native runtime library on the local machine.

Resolution order for most Receiver runtimes:

1. channel.runtimePath in the Hypertube configuration file for that Receiver channel
2. Technology-specific environment variable (table below)
3. Platform defaults (JAVA_HOME for JVM; embedded PHP when PHP_HOME is unset)

Node.js and Perl Receiver channels use runtimes bundled with the Hypertube package and do not expose separate HYPERTUBE_*_RUNTIME_PATH variables in the native launchers.

Hypertube diagnostics

GG_DEBUG (Gateway / protocol layer) and HYPERTUBE_DEBUG (Hypertube SDK) are independent. Enable diagnostic variables only in controlled environments; captured logs may contain payload or credential data.

Samples

Windows (PowerShell) — Python Caller, Ruby Receiver, in-memory

$env:HYPERTUBE_KEY = "<your-hypertube-license-key>"
$env:HYPERTUBE_RUBY_RUNTIME_PATH = "C:\Ruby34-x64\bin\x64-ucrt-ruby340.dll"

# Optional: point graftcode-config at a file instead of using cwd lookup
$env:graftcode-config = "C:\apps\my-caller\graftcode-config.json"

# Optional: protocol byte logging (redact before sharing)
$env:GG_DEBUG = "1"
$env:HYPERTUBE_DEBUG = "true"

graftcode-config.json:

{
  "licenseKey": "<your-hypertube-license-key>",
  "loggingLevel": "runtimeinfo",
  "runtimes": {
    "ruby": {
      "name": "default",
      "modules": "C:/receivers/my-ruby-package",
      "channel": {
        "type": "inMemory",
        "runtimePath": "C:/Ruby34-x64/bin/x64-ucrt-ruby340.dll"
      }
    }
  }
}

Linux / macOS (bash) — .NET Caller, Python Receiver, in-memory

export HYPERTUBE_KEY="<your-hypertube-license-key>"
export HYPERTUBE_PYTHON_RUNTIME_PATH="/usr/lib/x86_64-linux-gnu/libpython3.13.so"
# or: export HYPERTUBE_PYTHON_VERSION="3.13"

export graftcode-config="/opt/my-caller/graftcode-config.json"

export HYPERTUBE_LOGGING_LEVEL="runtimeinfo"
export HYPERTUBE_DEBUG_MODE="true"

JVM Receiver — JAVA_HOME vs explicit JVM library path

# Option A: JDK/JRE root (searched for libjvm.so / jvm.dll)
export JAVA_HOME="/usr/lib/jvm/java-21-openjdk-amd64"

# Option B: direct path when JAVA_HOME layout is non-standard
export HYPERTUBE_JVM_RUNTIME_PATH="/usr/lib/jvm/java-21-openjdk-amd64/lib/server/libjvm.so"

.NET Receiver — framework band and custom runtime config

export HYPERTUBE_NETCORE_RUNTIME_VERSION="net8.0"

# Use only when the default runtimeconfig.json does not match your installed runtime
export HT_NET_RUNTIME_CONFIG_PATH="/opt/receivers/MyReceiver.runtimeconfig.json"

PHP Receiver — optional external PHP installation

export PHP_HOME="/usr/local/php"
# When unset, Hypertube uses embedded PHP

Gateway (Docker)

export GC_PROJECT_KEY="dev:<jwt-copied-from-portal>"
docker run -d -p 80:80 -p 81:81 -e GC_PROJECT_KEY="$GC_PROJECT_KEY" --name receiver receiver:1.0.0

Remote execution (no embedded runtime paths)

When host is ws:// or wss://, the Receiver runs in Gateway. Set host and module through configuration or code; embedded HYPERTUBE_*_RUNTIME_PATH variables are not required on the Caller.

from my_graft_package.graft_config import GraftConfig

GraftConfig.host = "wss://gateway.example.com/ws"
GraftConfig.stateless = True

Programmatic remote host (field names vary — copy from Vision):

GraftConfig.Host = "ws://localhost/ws";
GraftConfig.Stateless = true;

Next steps

• Environment and configuration
• Configuration keys and precedence
• In-memory execution and Hypertube exceptions