Integrate into a Linux app

Downloads and public test settings#

This page is for developers who can edit and build the host app. To try the features first, use the no-code walkthrough or test-app guide above.

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. Target and prerequisites#

The Linux SDK is an integration preview, based on normal-user execution on Ubuntu 24.04. It is separate from the legacy ARMv5/Linux 2.6 xSpan product SDK. Build arm64/amd64 for each target ABI; a library built for macOS cannot be copied to Linux.

Install Go 1.26.x, a C compiler, make, Bash and a CA trust store. Record the target architecture and glibc version. Install ca-certificates and any required enterprise CA; do not disable TLS verification.

uname -m
getconf GNU_LIBC_VERSION
go version
sudo apt-get update
sudo apt-get install --no-install-recommends build-essential ca-certificates bash
# Run application builds and support as your normal user:
cd source
make sdk

2. Configuration and identity directory#

{
  "config": {
    "api_key": "sz_test_public",
    "device_name": "SDK integration test",
    "mode": "terminal"
  },
  "state_dir": "/home/operator/.local/state/streamzet-sdk-test",
  "fleet": false
}

The JSON below includes public test connection settings. Replace state_dir with a private absolute path for this user/installation, or run python3 configure-linux-test.py from the ZIP. JSON does not expand ~ or $HOME. The directory uses 0700 and identity.json 0600; do not share them with another SDK/agent or clone them into machine images.

chmod 600 config.json
mkdir -p /home/operator/.local/state/streamzet-sdk-test
chmod 700 /home/operator/.local/state/streamzet-sdk-test
./dist/sdk/native/embedded-example config.json
# Press Enter for a graceful stop.

3. Use from C/C++#

Use libstreamzet.h and libstreamzet.so from the same build. From the SDK source directory, the command below sets rpath to load the adjacent library. This ABI is not a Windows DLL or xSpan static library.

cc -Wall -Wextra -Werror -I dist/sdk/native examples/embedded.c \
  -L dist/sdk/native -lstreamzet -Wl,-rpath,'$ORIGIN' \
  -o dist/sdk/native/embedded-example
ldd dist/sdk/native/embedded-example
./dist/sdk/native/embedded-example config.json

#include "libstreamzet.h"
#include <stdio.h>

/* Call from a worker thread; config_json is NUL-terminated UTF-8. */
int run_support(char *config_json) {
    int rc = StreamzetStart(config_json);
    char *status = StreamzetStatus();
    puts(status);
    StreamzetFree(status); /* Exactly once, including error paths. */
    if (rc != 0) return rc;
    /* The real host continues its work here until support should end. */
    getchar();
    StreamzetStop(); /* Waits for peers/background work; not a UI callback. */
    return 0;
}

Start returns 0=started, 1=invalid configuration/start failure, 2=already started. Input JSON is copied during the call and remains caller-owned. Each Status string is caller-owned and must be released once with StreamzetFree. Stop is synchronous and idempotent; do not dlclose the Go library during process lifetime.

4. Integrate a Go host#

Do not assume a published version tag. Put the delivered source at vendor/streamzet-linux and add a local replace in the host module. Never import the SDK’s internal packages directly.

# Run inside your existing host Go module:
go mod edit -require=github.com/plitsoft/streamzet/[email protected]
go mod edit -replace=github.com/plitsoft/streamzet/linux-agent=./vendor/streamzet-linux
# After adding the SDK import to your host:
go mod tidy
# Or run the complete example shipped in the source package:
cd vendor/streamzet-linux
go run ./examples/go /absolute/path/config.json

import (
    "context"
    "github.com/plitsoft/streamzet/linux-agent/sdk"
)

func startSupport(ctx context.Context, options sdk.Options) (*sdk.Support, error) {
    support, err := sdk.Start(ctx, options)
    if err != nil { return nil, err }
    // support.Identity() returns only device ID/code; enrollment is asynchronous.
    // Keep support while the host performs its normal work.
    return support, nil
}

func stopSupport(support *sdk.Support) error {
    support.Stop() // Requests cancellation; nonblocking.
    return support.Wait() // Join before host shutdown, off the UI thread.
}

The complete runnable host is examples/go/main.go. Context cancellation/Stop requests shutdown; Done/Wait confirms completion. Only one instance per process is allowed. The SDK does not replace host signal handlers, call os.Exit or install the standalone updater.

5. Add desktop capture#

First verify connection and shutdown with mode=terminal. For GUI support, run mode=auto inside the logged-in user’s graphical session. Do not substitute another user’s DISPLAY, WAYLAND_DISPLAY, XDG_RUNTIME_DIR or DBUS_SESSION_BUS_ADDRESS.

sudo apt-get install --no-install-recommends pkg-config libgstreamer1.0-dev \
  libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-good gstreamer1.0-pipewire wl-clipboard
mkdir -p dist/sdk/native
cc -O2 -Wall -Wextra -Werror native/capture.c \
  -o dist/sdk/native/streamzet-capture \
  $(pkg-config --cflags --libs gstreamer-app-1.0)
# Set config.capture_helper to the ABSOLUTE path of streamzet-capture.
# Set config.mode to "auto".

Wayland requires PipeWire and the desktop’s xdg-desktop-portal backend, plus user sharing/control approval. Denial grants no desktop input; terminal access may remain available independently. X11 also requires display access and GStreamer plugins. File transfer is not supported by this SDK.

6. Delivery and operation#

Ship the target-ABI library, generated header, required capture helper, licenses and public configuration procedure with the host. Preserve the identity directory across updates and restrict backups. Dashboard online/connected states are distinct from the SDK’s running flag.