본문으로 건너뛰기
sstreamzet/docs
Linux SDK preview콘솔 열기
개발자 문서 / Linux SDK
API와 연동 가이드 · 수정 2026-09-22

Linux 예제 사용 가이드

C와 Go 예제로 등록, 웹 터미널, 화면 공유와 종료를 순서대로 확인합니다.

이 페이지에서1. 테스트 준비2. C 예제 실행3. 웹에서 터미널 왕복 확인4. Go 예제와 등록 보존5. X11 / Wayland 화면 확인문제 해결인수 기록과 지원 요청

1. 테스트 준비

Ubuntu 24.04 일반 사용자 계정에서 실행하세요. C 예제 embedded-example과 Go 예제 go-example은 콘솔 앱입니다. Android APK처럼 설치 화면이나 설정 창이 없으며 config.json을 파일로 받습니다. root/sudo 실행은 거부합니다.

  1. 전달 ZIP의 SHA-256과 내부 SHA256SUMS를 검사합니다. CPU 아키텍처와 배포판을 확인하고, 일치하지 않는 바이너리는 대상 장비에서 make sdk로 다시 빌드합니다.
  2. backend/public anon key/signaling 정보를 받고 전용 state_dir를 설정합니다. config.json은 0600, 상태 폴더는 0700으로 제한합니다.
  3. 처음에는 mode=terminal, fleet=false로 시작합니다. 같은 상태 폴더로 두 예제를 동시에 실행하지 않습니다.
설치 패키지·완전한 JSON·빌드 명령

2. C 예제 실행

sh
cd source
make sdk
chmod 600 /absolute/path/config.json
./dist/sdk/native/embedded-example /absolute/path/config.json

첫 JSON에서 running=true이면 SDK 워커가 시작된 것입니다. 등록이 완료되면 identity.device_code가 채워진 새 JSON이 출력됩니다. 입력 파일에 잘못된 필드가 있거나 root로 실행하면 error와 실패 종료 코드가 나옵니다. 화면에 명령을 입력하는 콘솔이 아니라 SDK 수명주기를 보여주는 예제입니다.

json
{"running":true,"error":"","identity":{"device_id":"<device UUID>","device_code":""}}
{"running":true,"error":"","identity":{"device_id":"<device UUID>","device_code":"<your 8-character code>"}}

3. 웹에서 터미널 왕복 확인

  1. 승인된 운영자가 Devices → Pair Device에서 표시된 코드를 연결하고 해당 Linux 기기의 제어 세션을 엽니다. 모니터 모드는 터미널 입력을 허용하지 않습니다.
  2. 웹 터미널에 아래 printf와 whoami를 입력합니다. SDK를 실행한 일반 사용자로 실행되는지, 한글과 영문이 돌아오는지 확인합니다. 실제 운영 명령이나 민감한 파일은 사용하지 않습니다.
  3. 브라우저 창 크기를 바꿔 stty size 결과가 갱신되는지 확인합니다. exit로 셸을 닫은 뒤 New terminal로 다시 여는 동작을 확인합니다.
sh
printf 'SDK_%s_OK\n' LINUX
printf '한글 UTF-8 확인\n'
whoami
stty size
웹 터미널의 실제 SDK_LINUX_OK 응답
Ubuntu 테스트 컨테이너에서 실행한 SDK와 운영 웹 뷰어의 실제 왕복 결과입니다.

4. Go 예제와 등록 보존

  1. C 예제 창에서 Enter를 눌러 running=false와 정상 종료를 확인합니다. 웹 화면의 종료 버튼은 해당 peer 연결을 종료하며 SDK 워커의 Start/Stop과는 별개입니다.
  2. 같은 config.json과 state_dir로 Go 예제를 실행합니다. 같은 device_id/device_code가 유지되는지 확인한 뒤 대시보드에서 다시 연결합니다.
  3. Enter로 Go 예제를 종료합니다. 실제 앱에 넣을 때는 UI 스레드 밖에서 Stop 후 Wait 완료를 기다리고, 호스트 작업은 지원이 끝나도 유지되도록 구현합니다.
sh
./dist/sdk/native/go-example /absolute/path/config.json
# Equivalent source run:
go run ./examples/go /absolute/path/config.json

5. X11 / Wayland 화면 확인

캡처 헬퍼와 그래픽 런타임을 설치한 후 config.mode를 auto로 바꾸고 capture_helper를 올바른 절대 경로로 지정합니다. 데스크톱에 로그인한 바로 그 사용자로 실행합니다. headless 기기는 터미널 전용이며 검은 영상이 나온다고 화면 기능이 있다고 간주하지 않습니다.

  1. X11: 테스트 편집기를 열어 영상 변화, 포인터, 클릭, 드래그, 스크롤과 문자 입력을 확인합니다. 접근 권한이 없는 디스플레이를 강제로 열지 않습니다.
  2. Wayland: 시스템의 화면공유/원격 제어 창에서 대상 화면과 원격 입력을 승인합니다. 대문자·기호·한글을 시험합니다. 텍스트 전송은 기기의 클립보드를 사용할 수 있습니다.
  3. Wayland 거부도 별도로 시험합니다. 화면/입력은 허용되지 않아야 하고, 정책상 열어 둔 터미널은 계속 동작할 수 있습니다. 사용자는 SDK 전체를 멈춰 터미널까지 종료할 수 있어야 합니다.
GNOME Wayland의 화면과 원격 입력 승인
실제 GNOME portal. 원격 입력이 필요하면 Allow Remote Interaction을 켜고 Share를 선택합니다.

문제 해결

증상확인과 조치
root remote shells are not supportedsudo를 제거하고 일반 사용자 계정으로 실행합니다.
state directory must be absolute/privateJSON의 경로를 실제 절대 경로로 지정하고 소유자·0700 권한·심볼릭 링크 여부를 확인합니다.
another agent owns this identity / already running다른 인스턴스를 정상 종료하고 재시도합니다. lock/identity 파일을 실행 중에 삭제하지 않습니다.
libstreamzet.so를 찾을 수 없음같은 ABI의 .so를 실행파일 옆에 놓고 제공된 rpath 빌드 명령을 사용합니다. ldd로 확인합니다.
running=true, 기기 코드 없음등록은 비동기입니다. DNS·HTTPS·CA 저장소·공개 키·방화벽을 확인하고 상태를 기다립니다. TLS 검증을 끄지 않습니다.
시작 직후 예제 종료stdin이 닫히면 정상 종료합니다. 터미널에서 실행하거나 컨테이너에 -i/-t를 유지합니다. 서비스 구현은 SDK 수명주기를 호스트에서 관리합니다.
Wayland 화면 불가로그인 세션·portal backend·PipeWire·승인·capture_helper를 확인합니다. 터미널 성공과 데스크톱 성공은 별개입니다.

인수 기록과 지원 요청

SDK 빌드/ZIP SHA-256, 배포판·kernel·CPU·glibc, X11/Wayland 세션, 호스트 사용자, 네트워크 경로, 기대/실제 결과와 재현 절차를 기록합니다. 테스트 후 모든 viewer를 종료하고 SDK Stop/Wait 또는 C Stop의 완료를 확인합니다. 설정 파일의 비밀 등록 키와 identity.json은 외부에 첨부하지 않습니다.