🍿 Popcorn: On-Demand Browser Service

Popcorn is an ultra-fast browser isolation service. It is designed to scale globally on Kubernetes, providing sub-second access to "warm" browser instances.

🏗 Architecture

Application Stack

• Pool Manager: Node.js service that assigns idle pods to users.
• Browser Node: Custom Docker image running Chromium with Neko.
• Agones (Fleets):
  • We use Agones to manage the lifecycle of browser sessions.
  • Fleets maintain a set of warm GameServers.
  • GameServers are "allocated" (marked as Busy) when a user connects.
• Gateway: OpenResty (Nginx) for sticky session routing.

---

🛠 Local Development

We use Kind (Kubernetes in Docker) to replicate the production environment locally.

Prerequisites

• Docker
• Kind (brew install kind)
• Kubectl
• Helm
• Make

Quick Start

Use the Makefile to control the local environment.

1. Build Images & Start Local Cluster:

   make build
   make up

   This starts a Kind cluster named popcorn and installs Agones.

   kubectl apply -k kustomize/dev # example, you need to provide your own manifests

2. Connect:

   make connect

   Forwards port 8080 to the gateway. Access at http://localhost:8080.

3. Reset:

   make clean

---

📦 Deployment Strategy (Production)

Popcorn is designed to be deployed on any standard Kubernetes cluster.

1. Build and push your own Docker images.
2. Deploy the core services (pool-manager, gateway, ttl-controller) using standard Kubernetes manifests or Helm charts.
3. Install Agones on your cluster and configure your browser-node fleets.

---

🔒 Security

• SEV-SNP Hardware Attestation: Popcorn instances run within an AMD cryptographic enclave. Attestation proofs dynamically bind the actively running container digests (e.g., neko browser) to a nonce, guaranteeing the exact codebase is running securely. Proofs can be fetched and verified using the tools in scripts/attestation/.
• Isolation: Every session runs in a dedicated ephemeral pod.
• Network: WebRTC traffic is routed via a private TURN server (Coturn) or internal ClusterIPs.

👥 Contributing

1. Clone the repo.
2. Run make up to stand up the local dev stack.
3. Make changes to services/.
4. Run make build and deploy to test.