The Problem

Most personal cloud platforms lock users into proprietary infrastructure or require complex, multi-service deployments. Puter addresses this by offering a self-hostable, open-source "internet OS" that consolidates files, apps, and games into a single accessible interface, giving individuals and organizations control over their data without vendor lock-in.

What This Does

Puter is a full-stack web platform. The src/backend/ directory contains the core server logic, including kernel architecture, authentication (src/backend/doc/A-and-A/auth.md), and permission handling. The extensions/ folder implements modular capabilities: puterfs provides a file system abstraction with pluggable storage controllers (LocalDiskStorageController.js, ProxyStorageController.js), metering tracks usage via UsageController.ts, and whoami exposes identity routes. A mods/ system allows runtime customization, with examples in mods/mods_available/.

The frontend is React-based, and the project ships with Docker support (Dockerfile, docker-compose.yml). CI/CD is configured via GitHub Actions (.github/workflows/), covering tests, Docker image builds, and release automation. Documentation is extensive—111 files—including self-hosting guides (doc/self-hosters/instructions.md) and extension development references.

How To Use It

Setup: Requires Node.js 24+ and npm. The README documents npm install followed by npm start.

Configuration: Environment variables go in .env.example (copy to .env). Docker Compose users need to create puter/config and puter/data directories with proper ownership, as shown in the README.

Running it: For local development, npm start launches the server at http://puter.localhost:4100. Docker users run the container image ghcr.io/heyputer/puter or use docker compose up with the provided docker-compose.yml.

Local development

git clone https://github.com/HeyPuter/puter cd puter npm install npm start

Docker

mkdir -p puter/config puter/data sudo chown -R 1000:1000 puter docker run --rm -p 4100:4100 \ -v pwd/puter/config:/etc/puter \ -v pwd/puter/data:/var/puter \ ghcr.io/heyputer/puter

Real-World Use

A small team could deploy Puter as an internal file-sharing and app-hosting platform. The puterfs extension enables custom storage backends—swap LocalDiskStorageController for a proxy to connect to S3 or network storage. The metering extension tracks per-user usage, useful for billing or quotas. Developers can build custom apps that run inside the Puter environment, exposed through the extension API (extensions/api.d.ts).

Code Health & Issues

Med - Monorepo complexity: 200 files across src/, extensions/, and mods/ with no clear top-level module boundaries; package.json files scattered per extension suggest dependency sprawl. Med - Testing gaps: Only 8 test files for a platform this size, and they're not centralized—coverage likely misses integration paths across extensions. Low - Documentation overload: 111 doc files, but many are planning docs (doc/planning/) or RFCS, which can confuse new contributors vs. stable reference material. Low - Hardcoded domain: README references puter.localhost; self-hosters may need to adjust config (doc/self-hosters/domains.md covers this, but it's an extra step). Low - Rust toolchain: rust-toolchain.toml exists but no Rust source files are visible—likely a build dependency that adds setup friction.

CI, license, and lockfile are present—good signs. No obvious secrets in the repo.

The Bottom Line

Puter is an ambitious, feature-rich platform with solid documentation and a clean Docker path. It's best suited to developers who want a customizable personal cloud or need to host a multi-user app environment, not for teams seeking a lightweight file server. The extension architecture is genuinely extensible, but the monorepo complexity and thin test coverage mean production use requires careful planning.