Skip to main content

Cloud Deploy

OpenHuman is a desktop application, but its Rust core (openhuman-core) is a headless JSON-RPC server that can be hosted in the cloud. Deploying the core standalone is suitable for:

  • Multi-device access, multiple desktop clients pointing to the same hosted core
  • Internal testers without local Rust toolchain
  • Long-running cron jobs/webhooks

This guide covers four deployment paths:

  1. DigitalOcean App Platform: One-click deploy
  2. DigitalOcean App Platform: Manual deploy via doctl
  3. Any VPS: Via Docker Compose
  4. Fly.io

What Gets Deployed​

Each path deploys a container running openhuman-core serve on port 7788. The public host should be behind the provider's TLS, e.g., https://core.example.com/rpc.

Prerequisites​

SettingRequiredDescription
OPENHUMAN_CORE_TOKENYesBearer token, generate: openssl rand -hex 32
BACKEND_URLYesOpenHuman backend (https://api.tinyhumans.ai for production)
OPENHUMAN_APP_ENVNoproduction or staging, defaults to production
OPENHUMAN_CORE_HOSTNoDefaults to 0.0.0.0
OPENHUMAN_CORE_PORTNoDefaults to 7788

1. DigitalOcean App Platform: One-click Deploy​

Click the button to create a new App Platform app:

Deploy to DO

Before first deploy completes, go to Settings → App-Level Environment Variables:

  1. Replace OPENHUMAN_CORE_TOKEN placeholder with a strong key
  2. Change OPENHUMAN_APP_ENV to staging if needed

2. Any VPS via Docker Compose​

Works on any host with Docker Engine ≥ 24. Production release image:

docker pull ghcr.io/tinyhumansai/openhuman-core:latest

Quick run:

docker run -d --name openhuman-core -p 7788:7788 \
  -e OPENHUMAN_CORE_TOKEN="$(openssl rand -hex 32)" \
  -e BACKEND_URL=https://api.tinyhumans.ai \
  -e OPENHUMAN_APP_ENV=production \
  -v openhuman-workspace:/home/openhuman/.openhuman \
  ghcr.io/tinyhumansai/openhuman-core:latest

3. Fly.io​

Prerequisites​

  • flyctl installed and authenticated
  • Fly.io account

Step 1 — Launch App​

fly launch --no-deploy --config .fly/fly.toml

Step 2 — Create Persistent Volume​

fly volumes create openhuman_workspace --size 5 --region <your-region> --config .fly/fly.toml

Important: Mount the workspace to a persistent volume, otherwise data will be lost on each redeploy.

Step 3 — Set Secrets​

fly secrets set OPENHUMAN_CORE_TOKEN="$(openssl rand -hex 32)"
fly secrets set BACKEND_URL="https://api.tinyhumans.ai"
fly secrets set OPENHUMAN_APP_ENV="production"

Step 4 — Deploy​

fly deploy --config .fly/fly.toml

Step 5 — Connect Desktop App​

In app/.env.local:

OPENHUMAN_CORE_RUN_MODE=external
OPENHUMAN_CORE_RPC_URL=https://<your-app-name>.fly.dev/rpc
OPENHUMAN_CORE_TOKEN=<your-token>

Continuous Deployment​

Pushes to the main branch automatically trigger redeploy.

Updates​

# Docker Compose
git pull && docker compose build && docker compose up -d

# Fly.io
fly deploy --config .fly/fly.toml

Logs​

# Docker Compose
docker compose logs -f openhuman-core

# Fly.io
fly logs --config .fly/fly.toml

FAQ​

Bearer Token Rotation​

# 1. Generate new token and update server-side .env
openssl rand -hex 32 > /tmp/new-token
sed -i.bak "s|^OPENHUMAN_CORE_TOKEN=.*|OPENHUMAN_CORE_TOKEN=$(cat /tmp/new-token)|" .env

# 2. Restart container
docker compose up -d --force-recreate openhuman-core

# 3. Update each desktop client

TLS Issues​

Use Caddy, nginx, or Traefik as a reverse proxy:

core.example.com {
  reverse_proxy localhost:7788
}

Next Steps​