Linux example guide

Downloads and public test settings#

Download the files below directly. The downloads guide provides the public test key and configuration; pair the device code in your own account for testing.

e22b4792bbdc58878c67c5104d182422f8accfea9da10379252e0a5296d3e57a

58d120c0f123169726077a8845ac2619692cb14b45058e72a5aaa80700d6e5d0

1. Prepare the test#

This walkthrough runs prebuilt examples on Ubuntu 24.04. No C/Go compiler or make is needed for the first trial. You need a terminal, Python 3 and internet access.

1. Open a terminal on Linux and check the Ubuntu version and CPU below. Download AMD64 for x86_64 or ARM64 for aarch64.
2. Extract the ZIP into a new folder. In the file manager, open the folder containing configure-linux-test.py and bin, then use Open in Terminal from its context menu. Run the commands there.
3. Run as your normal user; do not prefix example commands with sudo. Also open StreamZet Devices on a PC using your own account.

cat /etc/os-release
uname -m
python3 --version

2. Generate settings and run the C executable#

Run each line below from the extracted folder. The helper writes the public test key and a private state path under your home into config.json. No manual key or path editing is needed.

ls configure-linux-test.py bin/embedded-example
python3 configure-linux-test.py
chmod u+x bin/embedded-example bin/go-example
./bin/embedded-example config.json

After Created …/config.json, output shows running=true and identity. Once registration finishes, identity.device_code contains an eight-character code to register on the PC. Keep this window open: it shows the running example rather than accepting shell commands.

{"running":true,"error":"","identity":{"device_code":""}}
# After registration, read the device_code from your own output.

3. Verify the web terminal#

1. On the PC, register the printed code from Devices, then start that Linux device’s session in control mode and open Terminal. View-only mode does not allow terminal input.
2. Run the printf and whoami commands below in the web terminal. Verify the normal host user and round-trip English/Korean output. Do not use production-changing commands or sensitive files.
3. Resize the browser and check that stty size changes. Close the shell with exit and reopen it with New terminal.

printf 'SDK_%s_OK\n' LINUX
printf '한글 UTF-8 확인\n'
whoami
stty size

4. Go example and identity persistence#

1. Press Enter in the C console and confirm running=false and clean exit. The web End connection button ends that peer session; it is separate from starting/stopping the SDK worker.
2. Run the Go example with the same config.json/state_dir. Confirm the same device_id/device_code, then reconnect from the dashboard.
3. Press Enter to stop the Go example. For later runs, reuse config.json; you do not need to run the configuration helper again.

./bin/go-example config.json
# Press Enter to stop.

5. Verify X11 / Wayland desktop#

After installing the capture helper and graphical runtime, set config.mode=auto and an absolute capture_helper path. Run as the logged-in desktop user. A headless machine is terminal-only; a black video is not evidence of desktop support.

1. X11: open a test editor and verify changing video, pointer, click, drag, scroll and text. Do not force access to an unauthorized display.
2. Wayland: approve the target screen and remote interaction in the system portal. Test uppercase, symbols and Korean. Text transport may use the device clipboard.
3. Test Wayland denial separately: it must grant no screen/input. A terminal allowed by host policy may continue, and the host must let the user stop the SDK to end terminal availability too.

Troubleshooting#

Acceptance record and support#

Record SDK build/ZIP SHA-256, distro/kernel/CPU/glibc, X11/Wayland session, host user, network path, expected/actual result and reproduction steps. End all viewers and confirm SDK Stop/Wait or C Stop completion. Do not attach private enrollment keys or identity.json externally.

Developers: building from source#

Use the integration guide for tool setup, configuration and lifecycle when building for another environment or embedding into a host. These paths are relative to the SDK source folder and differ from the prebuilt bin paths above.

cd source
make sdk
./dist/sdk/native/embedded-example ../config.json
# Press Enter, then:
./dist/sdk/native/go-example ../config.json