--- title: Environment & Runtime Configuration description: Environment & Runtime Configuration --- [Skip to content](https://portal.sandgrain.eu/knowledge-base/environment-runtime-configuration#main-content) English Show submenu for translations ![SandGrain\_Logo\_RGB\_white-bijgesneden (1)](https://portal.sandgrain.eu/hs-fs/hubfs/SandGrain_Logo_RGB_white-bijgesneden%20(1).png?width=427&height=83&name=SandGrain_Logo_RGB_white-bijgesneden%20(1).png) Open main navigation Close main navigation - English Show submenu for translations - [Contact us](https://portal.sandgrain.eu/login) [Contact us](https://portal.sandgrain.eu/login?hsLang=en) How can we help you? - There are no suggestions because the search field is empty. 1. [Knowledge Base](https://portal.sandgrain.eu/knowledge-base?hsLang=en) 2. [SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en) 3. [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#sandgrain-sdk) October 6, 2026 # Environment & Runtime Configuration **Who this is for:** Developers configuring where the SDK runs and what it connects to. **What you'll accomplish:** Understand the environment-specific settings, the environment variables, and the runtime flags, most of which the launchers set for you via prompts. ### Environment-specific parameters (`config_poc.h`) These describe the local machine and topology: | Parameter | Meaning | | --- | --- | | `MAX_DEVICES` | Maximum device channels the Gateway handles | | `PORT_BASE` | The Gateway listens on consecutive ports starting from this base | | per-device socket port | The port for each device channel | | `SERVER_IP` | **The Gateway's address: not the cloud server.** A common point of confusion. | | `USB_COM_PORT` | Your COM port number on Windows (e.g. COM4 → `4`) | | `USB_TTY_PORT` / `USB_TTY_PREFIX` | Your serial device on Linux (e.g. `/dev/ttyACM0` → prefix `ACM`, port `0`) | Both USB settings are **runtime-overridable** via the launcher prompts or environment variables. #### Environment variables The launchers write these based on your prompts (see *Access & Credentials* for where each lands): - **Cloud / BE:** CyberRock base URL, Device ID, Cloudflare Access ID/secret → the Cloud app's `.env`. - **MQTT:** host / port / user / password → `.env`, `.env.gateway`, `.env.device`. - **`BE_URL`:** defaults to `http://:3000/api`, used by the Gateway to sync its whitelist from the backend. - **Tenant email / password:** → `device_credentials.json`. #### Runtime flags (launchers) The Device's default run mode is `--listen` (BE-driven). Other flags adjust behavior: | Flag | Effect | | --- | --- | | `--listen` | Default. Device subscribes to `sandgrain/v1/{tid}/cmd/run_auth`, triggered from the frontend/backend; the interactive menu still runs in parallel. | | `--menu` | Interactive menu only, turns off the BE listener. | | `--usb PORT` | Serial suffix (e.g. `0` → `/dev/ttyACM0`); skips auto-detect. | | `--sudo` | Run the binary under sudo (use if you're not in the `dialout` group). | | `--no-build` | Reuse the existing binary instead of rebuilding. | | `--no-cloud` | Don't start the local Python cloud agent (use when the TrustBridge stack provides it). | | `--no-detect-tid` | Skip reading the Token's TID at startup. | ### The two run modes, explained - **`--listen` (default):** The Device starts a backend listener in a background thread and also falls through to the interactive menu on the main thread. The two run in parallel, serialized by a mutex (`g_sdk_mutex`) so they never call the SDK at the same time. The frontend/backend can publish to `sandgrain/v1/{tid}/cmd/run_auth` with `{"mode":1|2|3}`, and the Device runs the matching flow. - **`--menu`:** The BE listener is off; you drive everything from the numbered menu. #### Security considerations - Disable debug flags and enable CRC for production (see [*Compile-Time Configuration*](https://portal.sandgrain.eu/knowledge-base/compile-time-configuration-sdk-sgr-config.h?hsLang=en)). - Protect MQTT and cloud credentials. - Ensure only whitelisted TIDs are accepted. - [User Documentation](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#main-content) - [Quick Starter Guide](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#quick-starter-guide) - [User Manual](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#user-manual) - [Whitepaper](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#whitepaper) - [Token Leaflet](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#token-leaflet) - [Claim Token Procedure](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#claim-token-procedure) - [Daisy Chain](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#daisy-chain) - [Release Note](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#release-note) - [Naming Convention](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#naming-convention) - [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#sandgrain-sdk) - [TrustBridge](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#trustbridge) - [API Documentation](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#main-content) - [Device API Integration](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#device-api-integration) - [Daisy Chain and Attestation](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#daisy-chain-and-attestation) - [SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#main-content) - [Core Functions](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#core-functions) - [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#sandgrain-sdk) [![SandGrain\_Logo\_RGB\_white-bijgesneden (1)-1](https://portal.sandgrain.eu/hs-fs/hubfs/SandGrain_Logo_RGB_white-bijgesneden%20(1)-1.png?width=427&height=83&name=SandGrain_Logo_RGB_white-bijgesneden%20(1)-1.png "SandGrain_Logo_RGB_white-bijgesneden (1)-1")](https://portal.sandgrain.eu/?hsLang=en) [mailto:email@email.com](mailto:email@email.com) Copyright © 2026, sandgrain.eu