Skip to content

Getting Started

Jump to bottom
joshuaaferguson edited this page Apr 25, 2026 · 2 revisions

Getting Started

This guide gets a StreamSpace deployment running and a first session streaming. For production hardening details (TLS, external DB, ingress, autoscaling) see docs/DEPLOYMENT.md.

Prerequisites

  • Kubernetes 1.19+ — k3s, k8s, or Docker Desktop with Kubernetes enabled work for labs
  • Helm 3.x, kubectl, and Docker/Containerd
  • PostgreSQL — bundled in the Helm chart for labs; bring your own for production
  • A storage class that supports ReadWriteMany — NFS, local-path, etc.
  • For local development: Go 1.25+, Node 18+

Clone the repos

git clone https://github.com/streamspace-dev/streamspace.git
git clone https://github.com/streamspace-dev/streamspace-templates.git
git clone https://github.com/streamspace-dev/streamspace-plugins.git   # optional

Install via Helm

cd streamspace
kubectl create namespace streamspace
kubectl apply -f manifests/crds/
helm install streamspace ./chart \
  --namespace streamspace \
  --set controller.config.ingressDomain=streamspace.local \
  --set ingress.enabled=false

Launch a session

The Helm install seeds a chrome-selkies template that points at the ghcr.io/streamspace-dev/chrome-selkies:latest image. Once the install completes, create a session:

kubectl apply -f - <<'EOF'
apiVersion: stream.space/v1alpha1
kind: Session
metadata:
  name: my-chrome
  namespace: streamspace
spec:
  user: demo
  template: chrome-selkies
  state: running
  resources:
    memory: 2Gi
EOF

Then either port-forward the UI:

kubectl -n streamspace port-forward svc/streamspace-ui 3000:80

…and open http://localhost:3000 to log in and view the session, or use ingress and visit https://streamspace.local.

The UI's session viewer embeds the Selkies WebRTC stream via the control plane's authenticated proxy at /api/v1/http/<session-id>/.

Sync external template & plugin repos

# values.yaml snippet
repositories:
  templates:
    enabled: true
    url: https://github.com/streamspace-dev/streamspace-templates
    branch: main
    syncInterval: 1h
  plugins:
    enabled: true
    url: https://github.com/streamspace-dev/streamspace-plugins
    branch: main

Note

The 195 inherited LinuxServer templates in streamspace-templates/ (under browsers/, webtop/, etc.) reference KasmVNC images and don't currently work end-to-end with the Selkies-only control plane. Use the chrome-selkies template under selkies/ while the Selkies-native catalog is being built out.

Local dev loop

# UI
cd ui
npm install
npm run dev
# → http://localhost:3000 (proxies /api → http://localhost:8000)

# API
cd api
go run ./cmd

# K8s Agent (against your kubeconfig)
cd agents/k8s-agent
go run . --api-url=http://localhost:8000

Run all tests:

go test -race ./...

Next steps

Clone this wiki locally