HeyPuter/puter: self-hosting the open-source internet computer

The problem Puter targets: one login for files, apps and a backend

Most self-hosted stacks ask you to assemble the pieces. A file sync tool here, a notes app there, a small database for the glue code, plus a separate host for anything that needs a server. Puter's pitch is that all of it ships as one product with one account system. The README frames the goal plainly: every app and feature you need to work, create and play under one roof, listing Notepad, Voice Recorder, Spreadsheet and Camera as bundled examples.

For developers the offer is broader than a desktop shell. The README points at AI, cloud storage, a key-value database and serverless workers as the primitives you build against, and adds that publishing to the App Store is how you reach users. That combination is the actual differentiator: a web OS plus a hosting surface for the apps written for it.

Who is this for? Two groups. First, people who want a personal or team desktop reachable from a browser and hosted on their own hardware. Second, developers who want the Puter APIs (puter.js, the KV store, workers) without depending on puter.com. The repository is TypeScript, the package description calls it a desktop environment in the browser, and the project describes itself as self-hostable rather than merely open source.

Architecture: Caddy, Valkey, MariaDB, DynamoDB-local and RustFS

The docker-compose.yml in the repository is the clearest statement of how Puter is put together. It defines six services plus a one-shot initialiser. Caddy sits in front as a reverse proxy, described in the compose comments as mirroring the production ALB and handling TLS plus Host fan-out. Valkey, the Redis-compatible server, backs caching and rate limiting. MariaDB holds the SQL data, and the compose file notes that Puter applies its schema on first boot. DynamoDB-local is the key-value store, with the table created by Puter itself. RustFS provides S3-compatible object storage, and an s3-init container creates the bucket before the application starts.

One detail in the Valkey service is worth reading closely. Puter's ioredis client speaks cluster mode only, so the compose file starts Valkey as a single-node cluster, assigns all 16384 slots on first boot, and sets cluster-require-full-coverage no. That is a deliberate workaround, and it tells you the application expects a cluster-capable client even in a small deployment.

Configuration flows through two files. The Dockerfile says self-hosters mount a config.json at /etc/puter/config.json, which is deep-merged over the bundled config.default.json, so partial overrides work and an absent file means defaults. Secrets and ports come from .env, which the example file warns are not safe beyond a local laptop test.

Installing Puter locally and reaching it on port 4100

The README's local development path is four commands. Clone the repository, install dependencies, start the server. The documentation states this should launch Puter at http://puter.localhost:4100, so that hostname and port are what you check in the browser after the process settles.

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

For a self-hosted deployment rather than a development checkout, the README gives a one-line installer for Linux and macOS, and a PowerShell equivalent for Windows. The compose file comments say the script fetches the compose file, generates secrets, writes .env and config.json, and runs the compose up for you.

curl -fsSL https://puter.com/selfhost | sh

irm https://puter.com/selfhost?os=windows | iex

If you prefer to drive it yourself, the compose file lists the manual sequence: copy .env.example to .env, drop a config.json into ./puter/config/ using the example in selfhosted/full-stack.md, then run docker compose up -d. The .env.example sets HTTP_PORT=80 by default and leaves HTTPS_PORT commented until you enable TLS in caddy/Caddyfile. The same file carries MARIADB_ROOT_PASSWORD, MARIADB_DATABASE, MARIADB_USER, MARIADB_PASSWORD, S3_ACCESS_KEY, S3_SECRET_KEY and S3_BUCKET, all of which the example tells you to replace.

Where Puter is the wrong tool, and what the docs leave open

The dependency graph is the first limitation. A working self-hosted Puter is not one process. It is MariaDB, Valkey, DynamoDB-local, RustFS, Caddy and the application, and the compose file itself flags that state-bearing volumes should be moved to a backed-up location and that default passwords, S3 keys and Puter secrets must be replaced for production. If your requirement is a single static binary on a small VPS, this is the wrong shape.

TLS is a manual step. The .env.example ships HTTP_PORT=80 and leaves HTTPS_PORT=443 commented out, pointing at caddy/Caddyfile. Nothing in the README describes automatic certificate issuance, so exposing the stack before you edit that file means plain HTTP.

Upgrade and rollback are the thinnest part of the documentation. The compose comments say Puter applies its schema on first boot, which implies migrations run at startup, but the README does not document rollback, downgrade or a migration dry run. Before you run a new image against a database you care about, take a dump; the project gives you no documented way back.

Finally, scope. Puter is a consumer-facing desktop with an app platform, not a general-purpose PaaS. The serverless workers and KV store are tied to Puter's own account and app model, so they will not replace a container scheduler or a managed queue for backend services.

How Puter differs from Nextcloud and from a plain static host

Nextcloud is the closest comparison most self-hosters will make, and the difference is in the unit of extension. Nextcloud is a file platform with apps bolted onto a PHP core; the primary object is a file or a folder, and its apps extend that metaphor. Puter's primary object is a web application running inside a desktop shell, with storage, a KV database and workers offered as APIs to that application. If your users mainly want to sync documents and calendars, Nextcloud's model fits better. If you are building browser apps and want a hosting surface with storage and compute attached, Puter's model is the one that matches.

The second comparison is a static host plus a backend-as-a-service. That combination can cover the same ground, but you assemble it: one provider for the CDN, another for the database, a third for the object store. Puter collapses those into a single deployment you operate, at the cost of running all six containers yourself. The trade is control and data locality against operational surface.

Licence and the cost of running a modified public instance

The repository, including its sub-projects, modules and components, is licensed AGPL-3.0 unless stated otherwise, and package.json records AGPL-3.0-only. Third-party libraries included in the repository may carry their own licences, which the README notes explicitly.

The practical consequence for a self-hoster is the network clause. If you modify Puter and let users interact with it over a network, the AGPL's source-availability obligation is the thing to read before you plan a private fork. Running an unmodified copy for yourself is a different situation from operating a modified public service, and the repository does not give legal advice on either. There is also a TRADEMARK.md at the repository root, so the licence covers code while the name is handled separately.

Upgrade cost is a function of the release cadence. The recent releases are dated 2026-08-06, 2026-08-12 and 2026-08-24, roughly fortnightly, with the last push on 2026-08-24. That rhythm means you should expect to pin an image tag rather than track latest, and to re-read config.template.jsonc when you bump, because the Dockerfile deep-merges your mounted config.json over the bundled defaults and a renamed key will silently fall back.

Editorial conclusion

Adopt Puter if you want a self-hosted browser desktop with a developer API surface, and you are willing to run MariaDB, Valkey, DynamoDB-local and S3-compatible storage behind Caddy. Do not adopt it if you need a single-binary deployment or cannot accept AGPL-3.0 obligations for a modified public service. Verify first that your Caddy TLS configuration and the .env secrets are set before exposing port 80, and confirm the schema migration path yourself, because the README does not document rollback.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes