StreamSpace

Stream any app to your browser

An open source, platform-agnostic container streaming platform

Features • Quick Start • Architecture • Documentation • Contributing

---

Warning

Active rebuild — April 2026. The control plane and agents work, but the end-to-end streaming pipeline (image build, template catalog wiring, golden-path test) is being reconstructed. The historical v2.0-beta.1 docs are preserved under docs/historical/ for context.

Overview

StreamSpace delivers browser-based access to containerized applications. A central Control Plane (API + WebUI) brokers sessions to distributed Agents running on Kubernetes today and Docker next.

Streaming uses Selkies-GStreamer (WebRTC) end-to-end. Earlier VNC code paths were removed in favor of a single, well-supported protocol.

Repository topology

Repo	What it owns
streamspace-dev/streamspace (this repo)	Control Plane API, K8s/Docker agents, Web UI, Helm chart
streamspace-dev/streamspace-templates	Application templates (CRD manifests) and the source + build pipeline for custom container images (ghcr.io/streamspace-dev/<image>)
streamspace-dev/streamspace-plugins	Optional plugins (auth, storage, observability, billing, …)
streamspace-dev/streamspace.wiki	End-user documentation (Getting Started, Architecture overview, Plugin/Template catalogs)

Features

Core	Enterprise
Browser-based streaming over WebRTC	SSO: SAML 2.0, OIDC, OAuth2
Multi-tenancy with org scoping	MFA with TOTP
Persistent home directories	Audit logging & compliance
Auto-hibernation (scale to zero)	IP allow-listing & rate limiting
Custom image pipeline (cosign + SBOM)	Webhooks (16 event types)
Grafana dashboards	Prometheus alerts

Quick Start

Note

This is the dev/contributor flow. For production deployment see docs/DEPLOYMENT.md.

Prerequisites

• Kubernetes 1.19+ (k3s recommended for local dev)
• Helm 3.0+
• PostgreSQL database
• A storage class for persistent home volumes

Install

git clone https://github.com/streamspace-dev/streamspace.git
cd streamspace
kubectl apply -f manifests/crds/
helm install streamspace ./chart -n streamspace --create-namespace

Launch a session

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

The chrome-selkies template is the seeded default. The control plane proxies /api/v1/http/<session-id>/ to the session pod's Selkies endpoint on port 8080.

Tip

Update default secrets before any production deployment — see docs/DEPLOYMENT.md.

Architecture

graph TD
    User[User / Browser] -->|HTTPS| Ingress[Load Balancer]
    Ingress -->|HTTPS| UI[Web UI]
    Ingress -->|HTTPS / WSS| API[Control Plane API]

    subgraph "Control Plane"
        UI
        API
        Hub[Agent WebSocket Hub]
        Selkies[Selkies HTTP/WebRTC Proxy]
        DB[(PostgreSQL)]

        API --> DB
        API --> Hub
        API --> Selkies
    end

    subgraph "Execution Plane — Kubernetes"
        K8sAgent[K8s Agent]
        K8sAgent <-->|WebSocket| Hub
        K8sAgent -->|Manage| Pods[Session Pods]
        Selkies -.->|HTTP/WS| Pods
    end

    subgraph "Execution Plane — Docker"
        DockerAgent[Docker Agent]
        DockerAgent <-->|WebSocket| Hub
        DockerAgent -->|Manage| Containers[Session Containers]
    end

Loading

Components

• Control Plane API — auth, multi-tenancy, session orchestration, exposes the Selkies HTTP/WebRTC proxy.
• Agent WebSocket Hub — bidirectional command channel to agents (heartbeats, session start/stop, status updates).
• Selkies Proxy — token-authenticated reverse proxy from /api/v1/http/<session>/ to the in-cluster Selkies endpoint on the session pod (port 8080). Sessions stream over the same connection via WebRTC.
• K8s Agent — manages Session/Template CRDs, deploys session pods, reports lifecycle.
• Docker Agent — equivalent for Docker hosts (in flight).

For the deeper technical reference, see docs/ARCHITECTURE.md. Frozen v2 architecture snapshots live in docs/historical/.

Available applications

Templates live in streamspace-templates. The image-build pipeline in that repo publishes signed images to ghcr.io/streamspace-dev/<image> with cosign keyless signatures and SPDX SBOM attestations.

Currently published:

• ghcr.io/streamspace-dev/chrome-selkies:latest — Google Chrome streamed via Selkies-GStreamer (linux/amd64; arm64 pending upstream Selkies binaries)

Note

The package on GHCR may be private by default. Org admin can flip it to public via the package settings page. Once public, anonymous pulls and the cosign verification command in streamspace-templates/images/README.md work without auth.

A Selkies-native catalog (Firefox, VS Code, full desktops, etc.) is being added on top of the same pipeline.

Development

# Build K8s Agent
cd agents/k8s-agent && go build -o k8s-agent .

# Build API
cd api && go build -o streamspace-api ./cmd

# Build UI
cd ui && npm install && npm run build

# Run all Go tests under -race
go test -race ./...

See docs/TESTING.md for the full test guide.

Documentation

Contributor-facing (this repo)

• docs/ARCHITECTURE.md — system design
• docs/DEPLOYMENT.md — production deployment
• docs/MIGRATION_V1_TO_V2.md — v1 → v2 migration
• docs/design/architecture/ — architecture decision records
• docs/historical/ — frozen architectural snapshots
• CONTRIBUTING.md · ROADMAP.md · FEATURES.md

End-user-facing

• streamspace.wiki — Getting Started, deployment, plugin/template catalogs

API

• Swagger UI at /api/docs (when API is running)
• docs/API_REFERENCE.md

Contributing

Contributions welcome — start with CONTRIBUTING.md. The workflow is the standard fork → branch → PR pattern; see the project's issue board for triaged work.

License

StreamSpace is licensed under the MIT License.

---

_{Built with ❤️ by the StreamSpace Team}