How to Deploy OpenHuman on a VPS: Step-by-Step Guide

OpenHuman is an open-source personal AI assistant by TinyHumans AI. Unlike chatbots that forget you after each session, OpenHuman builds a persistent memory — it ingests your documents, emails, and messages into a local knowledge base and remembers context across weeks. It runs as a desktop app on your Mac or PC, connected to a server (the "core") that does the heavy lifting.

We deployed the whole thing on an is*hosting VPS. This guide documents every step, every error we hit, and every fix. The process took about an hour total, most of it waiting for Rust to compile.

What You'll Need

• An is*hosting VPS (with 8+ GB RAM)
• A Mac or Windows computer
• A Google, GitHub, or Twitter account (for OpenHuman login)
• About 60 minutes (40 of which is waiting for compilation)

Step 1: Order a VPS

Head to is*hosting and order a VPS with:

• RAM: 8 GB minimum
• Storage: 40 GB NVMe
• OS: Ubuntu 24
• Location: pick whatever's closest to you

Price: $24.99/mo (or $21.24/mo on an annual plan) for Medium VPS + $10/mo extra for additional RAM. Or $39.99/mo (or $31.99/mo on an annual plan) for Premium VPS.

We tried the setup on Medium VPS + 4 GB RAM.

OpenHuman's core is written in Rust, and compiling Rust from source requires 6-8 GB of peak memory. With the stock 4 GB, the build process gets killed by the OS (OOM). We learned this the hard way — 40 minutes of compilation, then signal: 9 and start over.

After payment, you'll receive an IP address and root password via email. Save both.

Step 2: Connect to Your Server via SSH

Mac: Open Terminal.

Windows: Download Tabby or use PowerShell.

Type:

ssh root@YOUR_IP_ADDRESS

Replace YOUR_IP_ADDRESS with the actual IP from your email. Example:

ssh [email protected]

First connection will ask: "Are you sure you want to continue connecting?" — type yes and press Enter.

Then paste your password. The password won't show on screen — that's normal. Just paste and hit Enter.

When you see root@server:~# — you're in.

Step 3: Install Docker

OpenHuman runs in a Docker container. One command installs it:

curl -fsSL https://get.docker.com | bash

Wait for completion (1-2 minutes). You'll see some warnings about rootless mode — ignore them.

Step 4: Clone OpenHuman and Configure

Download the source code:

cd /root
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

Create the config file:

cp .env.example .env

Generate a secure token (this is the password your desktop app will use to connect to the server):

openssl rand -hex 32

Copy the output — you'll need it twice: once for the server config, once for the desktop app.

Edit the config:

nano .env

Scroll to the very end of the file and add one line:

OPENHUMAN_CORE_TOKEN=PASTE_YOUR_TOKEN_HERE

Everything else can stay as defaults — BACKEND_URL defaults to production, OPENHUMAN_APP_ENV defaults to production.

Save: Ctrl+O → Enter → Ctrl+X.

Step 5: Build and Start OpenHuman

This is the big step. Docker will compile the Rust core from source:

docker compose up -d

You'll see a yellow warning: "pull access denied for openhuman-core" — that's normal. The pre-built image isn't on Docker Hub, so it builds locally instead.

This takes 10-20 minutes. The terminal will show compilation progress. Don't close it.

If the build fails with signal: 9: Your server ran out of memory. You need at least 8 GB RAM for compilation. See Step 1 — add +4 GB RAM via support ticket and try again.

When it finishes, you'll see four green checkmarks:

✔ Image openhuman-core:local    Built
✔ Network openhuman_default     Created
✔ Volume openhuman-workspace    Created
✔ Container openhuman-core      Started

Step 6: Fix the Entrypoint (You'll Probably Need This)

Check if the core is actually running:

curl -s http://localhost:7788/health

If you get a JSON response with "pid" — skip to Step 7.

If you get nothing or "Connection refused," check the logs:

docker logs openhuman-core --tail 20

If you see chown: Operation not permitted repeating in a loop: The container's entrypoint script can't change file ownership on the Docker volume. This is a known issue on VPS environments.

Fix — edit the Docker Compose file to bypass the entrypoint:

nano /root/openhuman/docker-compose.yml

Find the services: → openhuman-core: block and add these two lines right under openhuman-core: (with proper indentation — 4 spaces):

    user: "0:0"
    entrypoint: ["/usr/local/bin/openhuman-core", "serve"]

Save, then restart:

docker compose down
docker compose up -d

Wait 5 seconds, then verify:

curl -s http://localhost:7788/health

You should get a JSON response. Check logs for errors:

docker logs openhuman-core --tail 10

If you see Failed to create workspace directory errors: Fix by recreating the Docker volume:

docker compose down
docker volume rm openhuman-workspace
docker volume create openhuman-workspace
docker compose up -d

(Ignore the warning about "volume already exists but was not created by Docker Compose" — it's harmless.)

Step 7: Set Up a Domain with HTTPS

The OpenHuman desktop app requires an HTTPS connection — it won't connect to a plain http:// IP address. You need a domain name and an SSL certificate.

If you don't have a domain, use DuckDNS (free):

• Go to duckdns.org, sign in with Google
• Create a subdomain (e.g., myopenhuman) — it becomes myopenhuman.duckdns.org
• Set the IP to your VPS IP address

Install Caddy (a web server that handles SSL automatically):

apt install -y caddy

Configure Caddy:

nano /etc/caddy/Caddyfile

Delete everything in the file (hold Ctrl+K until empty) and paste:

YOUR_DOMAIN.duckdns.org {
    reverse_proxy localhost:7788
}

Replace YOUR_DOMAIN.duckdns.org with your actual DuckDNS domain.

Save and restart:

systemctl restart caddy

Wait 10-15 seconds. Caddy automatically obtains an SSL certificate from Let's Encrypt.

Open the firewall ports:

ufw allow 7788/tcp
ufw allow 443/tcp

Test from your Mac terminal (not the SSH session):

curl -v https://YOUR_DOMAIN.duckdns.org/health

Should return HTTP/1.1 200 OK.

Step 8: Download and Connect the Desktop App

Download OpenHuman for Mac from tinyhumans.ai/openhuman

Install the DMG. Launch the app.

On the first screen, you'll see Select a Runtime options. Choose Run on the Cloud and paste:

• URL: https://YOUR_DOMAIN.duckdns.org/rpc
• Token: the token you generated in Step 4

Click Test Connection — it should show "Connected." Then click Continue.

Then sign in with Google, GitHub, or Twitter.

If sign-in fails ("could not start"): make sure the workspace directory error is fixed (Step 6). OAuth needs a working workspace to store session data. 

After login, you'll see the setup screen: Simple or Run Custom.

• Simple — OpenHuman manages models for you, $1 free credit included
• Run Custom — bring your own API keys (OpenRouter, Anthropic, etc.)

Pick whichever suits you.

Step 9: Verify Everything Works

Once past the setup screen, try sending a message in the chat. The agent should respond.

Check that the server is healthy:

docker logs openhuman-core --tail 10

Logs should show clean -> ok entries without errors.

Troubleshooting

Build fails with signal: 9 (OOM kill)

The Rust compilation needs 6-8 GB peak RAM. If your VPS has 4 GB, the OS kills the process.

Fix: Add +4 GB RAM to your VPS via support ticket ($10/mo). Or order Premium (8 GB) from the start.

chown: Operation not permitted loop

The default entrypoint tries to change file ownership inside the container. On VPS Docker setups, this fails silently and loops forever.

Fix: Add user: "0:0" and override the entrypoint in docker-compose.yml:

services:
  openhuman-core:
    user: "0:0"
    entrypoint: ["/usr/local/bin/openhuman-core", "serve"]

Failed to create workspace directory

The workspace volume has wrong permissions after the chown fix.

Fix:

docker compose down
docker volume rm openhuman-workspace
docker volume create openhuman-workspace
docker compose up -d

Desktop app says "Unreachable: Failed to fetch"

The app can't connect to your server. Three possible causes:

• Port not open. Run ufw allow 7788/tcp and ufw allow 443/tcp on the server.
• Using http:// instead of https://. The app requires HTTPS. Set up Caddy (Step 7).
• Wrong URL. Make sure it's https://YOUR_DOMAIN/rpc — with /rpc at the end.

Verify connectivity from your Mac terminal:

curl -v https://YOUR_DOMAIN.duckdns.org/health

"Cloud core needs an update" / version mismatch

The server core version doesn't match the desktop app version. Update the server to match:

cd /root/openhuman
git fetch --tags
git checkout v0.54.0
docker compose down
docker compose build --no-cache
docker compose up -d

Replace v0.54.0 with whatever version the desktop app expects. Check the latest at github.com/tinyhumansai/openhuman/releases.

This triggers another 20-minute rebuild.

OAuth sign-in fails ("could not start")

Usually caused by the workspace directory not being created. Fix the workspace (see above), restart the container, and try again.

If it still fails, try a different sign-in method (GitHub instead of Google, or vice versa).

Useful Commands

docker compose up -d                          # start OpenHuman
docker compose down                           # stop OpenHuman
docker compose restart                        # restart after config changes
docker logs openhuman-core --tail 30          # view recent logs
docker exec openhuman-core openhuman-core --version  # check version
curl -s http://localhost:7788/health          # health check
systemctl status caddy                        # check Caddy/SSL status

What You've Built

After following this guide, you have:

• OpenHuman core running 24/7 on a VPS in a Docker container
• HTTPS access via Caddy + free DuckDNS domain
• Desktop app on your Mac connected to the remote core
• Persistent memory and workspace that survives restarts
• Auto-restart via Docker's restart policy

The core keeps running even when your laptop is off. Your memory, integrations, and agent state live on the server.

What's Next

Once you're comfortable:

• Connect integrations — Gmail, Google Calendar, GitHub, Notion, Slack
• Build your memory tree — let OpenHuman ingest your documents and emails
• Add voice — OpenHuman supports speech-to-text and text-to-speech
• Set up cron tasks — automate recurring agent workflows
• Try local models — run Ollama on the same VPS for fully private inference (needs 16 GB+ RAM)

Full documentation: tinyhumans.gitbook.io/openhuman