Installation Quickstart

This guide shows you two ways to get started with MolnOS quickly: running it locally on your machine, or deploying it to free cloud services for a demo accessible from anywhere.

Authentication Options

MolnOS supports two authentication methods:

Option 1: Email-based passwordless signin (requires SMTP)

• Uses magic links sent via email
• Requires access to an SMTP server with app passwords
• Supported providers: Proton, Google, Apple iCloud, Yahoo, Zoho
• Important: Many cloud providers block SMTP—ensure your infrastructure allows SMTP connections on port 465 or 587

Option 2: OAuth authentication (no SMTP required)

• Use Google, GitHub, Microsoft, GitLab, or self-hosted providers (Keycloak, Authentik)
• Eliminates SMTP dependency for complete autonomy
• See OAuth Authentication for configuration details

You can use one method or both for maximum flexibility.

Local

Run MolnOS Locally

The fastest way to try MolnOS is to run it on your local machine.

Prerequisites

• Node.js 24 or later (download)
• Basic comfort with command-line interfaces
• 10 minutes of your time

All of the below assumes Linux or MacOS or that you use equivalent tooling as expressed in the steps.

Step 1: Install MolnOS

Choose your installation method. The npm method is the quickest way to get started, while the CLI installer provides additional CLI tooling for managing MolnOS.

npm (Easiest)

Since version 1.0.3, you can install MolnOS Core directly via npm:

Global installation:

npm install -g molnos

Then run it with:

molnos

Local installation:

npm install molnos

Then run it with:

npx molnos

CLI Installer

Install the MolnOS CLI:

curl -sSL https://releases.molnos.cloud/install.sh | bash

Install the MolnOS Core using the CLI tool:

molnos install

Step 2: Configure MolnOS

Create a configuration file manually (as per below) or generate a scaffold using:

molnos init

Configuration Location Matters

Currently, configuration files are only picked up from the installation directory, i.e. ~/.molnos/. Make sure to place the file there if it’s not already there.

Edit molnos.config.json with your email settings. For local testing, you can use a service like Mailpit or your own SMTP server:

{
  "$schema": "https://schemas.molnos.cloud/schema-config-v1.json",
  "version": "1",
  "email": {
    "emailSubject": "Sign In To MolnOS",
    "user": "[email protected]",
    "password": "your-smtp-password",
    "host": "localhost",
    "port": 1025,
    "secure": false
  },
  "auth": {
    "jwtSecret": "your-secret-key-change-this",
    "consoleUrl": "http://localhost:8000"
  },
  "server": {
    "allowedDomains": ["*"]
  },
  "molnos": {
    "dataPath": "data",
    "initialUser": {
      "userName": "User",
      "email": "[email protected]"
    }
  }
}

Note

SMTP for Testing With Email Sign-In

For local development, Mailpit offers a free SMTP testing service that catches all emails in a sandbox—perfect for trying MolnOS without sending real emails!

For Mailpit, make sure to run it with mailpit --smtp-auth-accept-any --smtp-auth-allow-insecure.

Step 3: Download and Configure the Console

Download the MolnOS Console from releases.molnos.cloud and extract it.

Open config.json in a text editor and verify the MolnOS Core (API) endpoint configuration:

{
  "api": {
    "baseUrl": "http://localhost:3000"
  }
}

Note: The default configuration automatically uses http://localhost:3000 when accessing the app via localhost, which matches MolnOS’s default port.

Step 4: Start MolnOS Core and Console

Start the MolnOS Core:

molnos start

In a separate terminal, serve the MolnOS Console using any static file server:

# Navigate inside of the console directory
cd path/to/molnos-console

# Simple example using a basic Node.js package called http-server
npx http-server -o -p 8000 --proxy http://localhost:8000?

You should receive an email asking you to join your MolnOS organization. MolnOS automatically invites the initial user’s email when there is no existing data.

Step 5: Sign In

1. Click the join button in the email you have received (the one you set as INITIAL_USER_EMAIL)
2. MolnOS will process your join request and you’ll be able to sign in
3. Sign in with your email in the Console
4. Check your inbox for a magic link from MolnOS
5. Click the link to complete sign-in
6. You’re in! Start exploring MolnOS’s features.

Port Configuration

The defaults are:

• Core: http://localhost:3000 (configured in MolnOS)
• Console: http://localhost:8000 (your static file server)

These are automatically configured to work together. If you change ports, update:

• Core: auth.consoleUrl in molnos.config.json to match your console port
• Console: api.baseUrl in config.json to match your API port

Cloud

Deploy to the Cloud

Get MolnOS running using free cloud services so you can try it from anywhere without local setup. Perfect for quick demos and evaluations.

What you’ll deploy

By the end of this guide, you’ll have:

• A MolnOS API running on DigitalOcean App Platform
• A MolnOS Console hosted on Netlify
• A working demo you can access from anywhere

Prerequisites

• Basic comfort with command-line interfaces
• A DigitalOcean account ($200 free credit)
• A Netlify account (free forever plan)
• 5 minutes of your time

Demo Limitations

This quickstart uses DigitalOcean App Platform’s ephemeral storage for simplicity. Data is not persisted between deployments. This description is only provided for demonstrational use.

Feedback Welcome

Cloud services change frequently. If you encounter issues with this guide, please let us know at [email protected] so we can keep it up to date.

Step 1: Deploy the Console

1. Download the MolnOS Console from releases.molnos.cloud

2. Create a redirects file for single-page app routing:

   • Create a new file named _redirects (no file extension) in the root folder
   • Add this single line:

   /*   /index.html   200

3. Deploy to Netlify:

   • Log into Netlify
   • Click “Add new site” → “Deploy manually”
   • Drag and drop your entire MolnOS folder into the upload area
   • Wait ~30 seconds for deployment to complete

4. Copy your site URL from Netlify (you will get a randomized name, which you can configure; it looks like https://something-random-here.netlify.app)

Custom Domain

Want to use your own domain? Netlify makes it easy—just add a custom domain in your site settings. Remember to update the CONSOLE_URL and ALLOWED_DOMAINS environment variables in DigitalOcean to match your custom domain.

Step 2: Deploy the MolnOS Core

1. Log into DigitalOcean and navigate to App Platform

2. Click “Create App”

3. Select “Container Image” and choose GitHub Container Registry

   • Repository: molnoscloud/molnos-core
   • Image tag: latest
   • Click Next

4. Configure your app:

   • Instance size: Select the smallest available ($5/month)
   • Region: Choose the closest datacenter to you
   • Network: Under HTTP Port, enter 3000

5. Add environment variables under “App-Level Environment Variables”:

   CONSOLE_URL=https://your-netlify-url.com/app
   ALLOWED_DOMAINS=https://your-netlify-url.com
   [email protected]
   INITIAL_USER_NAME=My Organization
   EMAIL_HOST=smtp.provider.com
   [email protected]
   EMAIL_PASSWORD=your-email-password
   EMAIL_PORT=465                                  # Example
   EMAIL_SECURE=true                               # If needed

   Important: Set Your Email

   Replace [email protected] and anything else above with your actual details. Note that the user specified in INITIAL_USER_EMAIL is where you’ll receive your sign-in link.

6. Review and create your app. Wait a minute or so for deployment to complete.

7. Copy your API URL from the app overview page (looks like https://molnos-core-xxxxx.ondigitalocean.app)

8. You should receive an email asking you to join your MolnOS organization. MolnOS automatically invites the initial user’s email when there is no existing data. For now, refrain from clicking the join button, as we need to finish configuring MolnOS.

Step 3: Reference the Core in the Console

1. Update the Core’s endpoint:

   • Open config.json in a text editor:

    {
      "api": {
        "baseUrl": "http://localhost:3000"
      }
    }

   • Replace https://molnos-core-xxxxx.ondigitalocean.app with your DigitalOcean API URL from Step 2

   Matching Configurations

   Make sure your API and console configurations match:

   • The console’s apiBaseUrl should point to your API endpoint
   • The Core’s CONSOLE_URL environment variable should point to your console’s /app path

   For this cloud setup:

   • Console → Core: Set in window.APP_CONFIG.apiBaseUrl
   • Core → Console: Already set as CONSOLE_URL=https://molnos.netlify.app/app

2. Redeploy to Netlify by dragging and dropping your entire MolnOS folder into the upload area. Redeployment is very fast, since only a single file is changed.

Step 4: Sign In

1. Click the join button in the email you have received (the one you set as INITIAL_USER_EMAIL)
2. MolnOS will process your join request and you’ll be able to sign in
3. Sign in with your email, now that you are part of the organization
4. Check your inbox for a magic link from MolnOS
5. Click the link to complete sign-in
6. You’re in! Start exploring MolnOS’s features.

CLI Commands

The MolnOS CLI provides several commands for managing your installation:

# Install the MolnOS Core (API)
molnos install

# Check for and install updates
molnos upgrade

# Create a config file template
molnos init

# Start the MolnOS Core server
molnos start

# Validate your MolnOS license key
molnos license

# Activate your MolnOS license key
molnos activate         # Implicit: picks "molnos.licenseKey" value from local molnos.config.json
molnos activate <key>.  # Explicit

# Deactivate your MolnOS license key
molnos deactivate       # Implicit: picks "molnos.licenseKey" value from local molnos.config.json
molnos deactivate <key> # Explicit

# Read the MolnOS documentation
molnos docs

# Read the MolnOS software agreement
molnos legal

# Remove MolnOS from your system
molnos uninstall

Updating MolnOS

To update to the latest version:

molnos upgrade

This checks for updates and installs them automatically. Your configuration and data are preserved.

Data Storage

MolnOS stores all data locally on your host:

• Installation: ~/.molnos/ (Core/API binary and version info)
• Configuration: molnos.config.json (in your working directory)
• Data: In the MolnOS folder and the data path (data, by default)

Backup Recommendations

Back up your working directory regularly, which contains:

• molnos.config.json (configuration)
• Database files

What’s Next?

Now that MolnOS is running, here’s what to explore:

• Read about the various features of MolnOS, such as Applications
• Want to tinker with the configuration?
• Curious? Read the architecture overview
• Issues? Find your answers on the troubleshooting page