Puter: An Open-Source Personal Cloud OS for Files, Apps, and Games

Puter is an open-source personal cloud operating system designed to give you full control over your files, applications, and games. It functions as a private cloud desktop where you can store data, run software, and work remotely from any location. Remarkably, a modest NAS with just 2GB of RAM is sufficient to host the entire platform.

• A private cloud: Store your files, apps, and games with global access and total privacy.
• A publishing platform: Build and host websites, web applications, and games.
• A Dropbox alternative: Provides familiar storage capabilities but with a more powerful and refined interface.
• A remote desktop: Connect seamlessly to servers and workstations.
• A learning lab: An ideal environment for experimenting with web development, cloud computing, and distributed systems.

Using Puter

Local Development

1. Clone the repository: git clone https://github.com/HeyPuter/puter
2. Enter the directory: cd puter
3. Install dependencies: npm install
4. Launch the application: npm start

Puter will run at http://puter.localhost:4100 (or the next available port). If you run into trouble, refer to the "First Run Issues" section of the documentation.

Docker

mkdir puter && cd puter && 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

Once running, the interface will be accessible at http://puter.localhost:4100.

Docker Compose

Linux / macOS

1. Create the necessary directories: mkdir -p puter/config puter/data
2. Set permissions: sudo chown -R 1000:1000 puter
3. Download the compose file: wget https://raw.githubusercontent.com/HeyPuter/puter/main/docker-compose.yml
4. Start the container: docker compose up

Windows

1. Create a project folder: mkdir puter then cd puter
2. Create the required subfolders:

   New-Item -Path "puter\config" -ItemType Directory -Force
   New-Item -Path "puter\data" -ItemType Directory -Force
   

3. Download the compose file:

   Invoke-WebRequest -Uri "https://raw.githubusercontent.com/HeyPuter/puter/main/docker-compose.yml" -OutFile "docker-compose.yml"
   

4. Start the container: docker compose up

Puter will be reachable at http://puter.localhost:4100.

Self-Hosting Puter

Differences From the Hosted Version

• You will not have direct access to applications specifically hosted on puter.com.
• Certain core applications, such as Code or Draw, may not be included in the self-hosted version.
• Some resource configurations may vary.

Configuration

The server generates a configuration file, the location of which depends on your installation method:

• Docker: config/config.json
• Local development: volatile/config/config.json
• Server or container: /etc/puter/config.json

Domain Setup

On the host machine, use the address displayed in the console (typically puter.localhost:4100).

To access Puter from other devices on your local network (LAN), enable the following setting: "allow_nipio_domains": true

For external access, point a domain and an api subdomain at your server's IP address (for example, example.com and api.example.com). You must then specify this domain in your config.json file (usually located at volatile/config/config.json).

Port Configuration

• Set http_port to your preferred custom value.
• If using a reverse proxy like Nginx or Cloudflare, set pub_port to the external port (commonly 443).
• When using a proxy with HTTPS, ensure the protocol setting in config.json matches.

Default User

Upon installation, Puter creates a user named default_user with a randomly generated password. The console will display this password and show a warning until it is changed. After your first login, be sure to update the password immediately for security.

System Requirements

• OS: Linux, macOS, or Windows
• RAM: 2GB minimum (4GB recommended)
• Disk space: 1GB free
• Node.js: Version 16 or newer (23+ recommended)
• npm: Latest stable version