puter - Moses Yebei

The Problem

Puter solves personal-cloud fragmentation: users juggle Dropbox, Drive, and OneDrive for files, apps, and games that should live in one place. It is a self-hostable internet OS — a desktop-like web environment with its own filesystem, auth, and app platform — so data stays on infrastructure you control rather than a commercial cloud.

What This Does

Puter is a full-stack system: src/backend is the Express server (services for auth, filesystem, database), src/gui is the React desktop UI, and extensions/ holds pluggable capabilities like puterfs (filesystem provider) and metering. The repo is a portfolio of five self-contained projects (src, extensions, tools, mods, eslint), not one monolith — treat them separately.

How It Is Wired

Execution starts at src/backend/src/index.js (testlaunch reaches 354 functions) or via run in src/backend/src/codex/Sequence.js (371 functions). Everything routes through three hub modules: src/backend/src/util/context.js (148 importers), src/backend/src/services/BaseService.js (143), and src/backend/src/api/APIError.js (120). These are high-blast-radius: changing them ripples across ~15% of the codebase.

Traced paths show a run touches the filesystem via ins.unlink (run -> arun), and crypto via jwt.sign (start -> id2path -> create -> get_user_app_token) and crypto.randomBytes(24) (init -> init_). Across the repo, 23 functions read/write files, 8 make outbound network calls, 20 do crypto, 4 hit a database, 3 call a model for inference. The hottest functions are $ (147 call sites), create (128), and on (62); install -> registerService is the most-called edge (165). The GUI has a circular import cycle in src/gui/src/UI/UIWindow.js and siblings.

How To Use It

The README documents the commands verbatim:

git clone https://github.com/moses-y/puter
cd puter
npm install
npm start

Docker: docker run --rm -p 4100:4100 -v ... ghcr.io/heyputer/puter. Configuration lives in .env.example and docker-compose.yml. Requires Node.js 24+, 2GB RAM.

Real-World Use

Self-hosted personal cloud: deploy with Docker Compose, mount puter/config and puter/data volumes, access at puter.localhost:4100. The extensions/puterfs/PuterFSProvider.js handles filesystem operations; src/gui renders the desktop. The extension system is the main integration point for custom capabilities.

Code Health & Issues

Measured analysis (static, not opinion): 524 findings (146 high, 346 medium, 32 low). High: deep nesting ×31 (src/backend/src/util/context.js max depth 6), oversized files ×3 (src/backend/src/helpers.js at 1277 lines), hub modules ×11. 22 modules sit in circular imports (GUI files). Fixes: early returns, splitting oversized files, breaking cycles.

SDLC audit — 8 findings, 0 critical:

High — unpinned GitHub Actions tags (e.g., docker/login-action@v3) in .github/workflows; pin to commit SHA.
Medium — no least-privilege GITHUB_TOKEN; no Dependabot; npm install instead of npm ci in CI; node:24-alpine base image unpinned by digest; no dependency vuln scan; persist-credentials not disabled.
Low — no timeout-minutes on workflow jobs.

The Bottom Line

A solid fork of a mature project (43k-star upstream) with clean hygiene — tests, CI, license, lockfile, no committed secrets. The hub modules and oversized files are the main maintainability risks. Good fit for teams wanting a self-hosted cloud OS; the extension system is the real value.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,584 files

JavaScript862
Markdown149
TypeScript147
JSON49
SQL41
CSS14

ReactExpressDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["src 914 modules"] g1["tests 58 modules"] g2["extensions 29 modules"] g3["tools 16 modules"] g4["mods 8 modules"] g5["doc 5 modules"] g6["eslint 4 modules"] g4 -->|7| g0 g2 -->|2| g0 g1 -->|2| g0 g3 -->|1| g0 g3 -->|1| g5

Module dependencies

The 10 most depended-upon modules of 1,037, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_backend_src_util_context["context"] n1_end_src_services_BaseService["BaseService"] n2_src_backend_src_api_APIError["APIError"] n3_src_backend_src_helpers["helpers"] n4_src_backend_src_config["config"] n5_src_services_database_consts["consts"] n6_kend_src_services_auth_Actor["Actor"] n7_rc_backend_src_api_eggspress["eggspress"] n8_src_gui_src_UI_UIWindow["UIWindow"] n9_rc_filesystem_node_selectors["selectors"] n4_src_backend_src_config --> n0_src_backend_src_util_context n3_src_backend_src_helpers --> n4_src_backend_src_config n3_src_backend_src_helpers --> n2_src_backend_src_api_APIError n3_src_backend_src_helpers --> n5_src_services_database_consts n3_src_backend_src_helpers --> n0_src_backend_src_util_context n3_src_backend_src_helpers --> n9_rc_filesystem_node_selectors n6_kend_src_services_auth_Actor --> n0_src_backend_src_util_context n6_kend_src_services_auth_Actor --> n3_src_backend_src_helpers n6_kend_src_services_auth_Actor --> n4_src_backend_src_config classDef cyc stroke:#ef4444,stroke-width:2px; class n8_src_gui_src_UI_UIWindow cyc;

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium6

low1

Pin third-party GitHub Actions to a commit SHAhigh8 occurrences

.github/workflows

docker/login-action@v3, docker/setup-qemu-action@v3, docker/setup-buildx-action@v3, docker/metadata-action@v5

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/main.yml

2 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

25 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Install from the lockfile in CImedium

.github/workflows

npm install with a committed package-lock.json

A fresh resolution in CI means the tested dependency set is not the locked one, so the failure only appears after merge.

Fix: Use npm ci, yarn install --immutable, or pnpm install --frozen-lockfile.

Pin the container base image by digestmedium2 occurrences

Dockerfile

node:24-alpine, node:24-alpine

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/test.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/docker-image.yaml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.