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.

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

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

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.

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

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/.

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)

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

# 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.

• 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

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

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

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

StreamSpace is licensed under the MIT License.