Puter

Puter is a self‑hosted, full‑stack Internet Operating System that consolidates file storage, web hosting, and remote desktop capabilities into a single, privacy‑first platform. From the perspective of a developer, Puter functions as an orchestrated microservices ecosystem where each core service—authentication, file management, app sandboxing, and networking—is exposed via well‑documented REST/GraphQL APIs. The architecture is intentionally modular: the front‑end communicates with a Node.js/Express gateway that proxies requests to containerized services written in Go, Rust, or Python, depending on the feature set. This separation allows developers to replace or extend individual components without touching the core runtime.

Architecture & Technical Stack

• Gateway Layer: A TypeScript‑based Express server that handles authentication, session management, and API routing. It serves the SPA built with React/Redux, leveraging WebSocket for real‑time file events and terminal emulation.
• Core Services: Each service runs in its own Docker container:
  • Auth & User Service: Go‑based microservice using PostgreSQL for credential storage and JWT for stateless auth.
  • File Service: Rust implementation that exposes a S3‑compatible API, backed by an encrypted PostgreSQL or SQLite database for metadata and raw file blobs stored in a local directory.
  • App Service: Python/Flask service that manages the App Store, sandboxing each user‑deployed web app in a separate Docker container with resource limits.
  • Remote Desktop: WebRTC‑based streaming service written in C++/Node.js, enabling low‑latency remote access to a virtual X11 session.
• Database & Storage: PostgreSQL is the default relational store for user and metadata; raw file data can be sharded across multiple volumes or external object stores (S3, MinIO). A Redis cache is used for session tokens and rate‑limiting.

Core Capabilities & APIs

• File System API: A RESTful interface (/api/files) that supports CRUD, directory listing, and bulk operations. WebSocket events notify clients of changes in real time.
• App Store API: Exposes endpoints for publishing, querying, and installing web apps. Apps are packaged as Docker images with a standardized entrypoint (/app/start), allowing developers to deploy any container‑ready web service.
• Remote Desktop API: Provides /api/desktop endpoints that establish WebRTC connections, enabling developers to embed a terminal or full desktop in any web page.
• Webhook & Event System: Users can subscribe to file events or app lifecycle events via HTTPS callbacks, facilitating integrations with CI/CD pipelines or external notification services.

Deployment & Infrastructure

Puter is designed for effortless self‑hosting. A single docker-compose.yml pulls all services, mounts persistent volumes for config and data, and exposes a single port (default 4100). For production deployments, the stack supports:

• Horizontal Scaling: Each service can be replicated behind a load balancer; the gateway uses sticky sessions to maintain user context.
• Kubernetes Support: Helm charts are available in the repository, enabling deployment on any cloud provider or on‑prem cluster.
• Zero‑Downtime Upgrades: Service containers can be updated independently, with the gateway routing new traffic to fresh instances while draining old ones.

Integration & Extensibility

Developers can extend Puter in multiple ways:

• Plugin System: The App Store acts as a plugin registry; third‑party developers can publish Docker images that register themselves via the /api/apps/register endpoint.
• Custom Auth Providers: The auth service exposes a pluggable strategy layer (OAuth, LDAP, SAML), allowing integration with existing enterprise identity solutions.
• Webhooks: Any event (file upload, app install) can trigger a webhook; developers can build downstream services that react to these events in real time.
• SDKs & SDK Docs: A TypeScript client library is available on npm, simplifying interaction with Puter's APIs from Node or browser environments.

Developer Experience & Community

The project prioritizes clean, auto‑generated documentation. The docs/ directory contains Markdown files that are rendered on the site, and API references are generated from OpenAPI specs. A Discord server and subreddit provide active community support; contributors are encouraged to open PRs against the monorepo, which is linted and tested with GitHub Actions. Licensing under Apache 2.0 removes any commercial barriers, making Puter an attractive choice for internal tooling or open‑source projects that require a self‑hosted cloud layer.

Use Cases

• Personal Cloud: Developers can host a private file store with fine‑grained ACLs, leveraging the S3 API for compatibility with existing tooling.
• Web App Platform: Teams can deploy and version web applications in isolated containers, using Puter's built‑in registry and auto‑scaling.
• Remote Development Environments: By combining the remote desktop service with a pre‑configured dev container, developers can expose IDEs or terminals to collaborators without exposing the underlying server.
• Educational Sandbox: Instructors can spin up isolated environments for students, each with its own file system and app store access, ensuring no cross‑talk between labs.

Advantages

• Performance: Rust and Go services provide low‑latency file operations, while WebRTC delivers near‑native remote desktop experience.
• Flexibility: The microservice architecture allows swapping out components