> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/features/cloud-deploy.md).

# Cloud Deploy

Run the headless openhuman-core on a server: DigitalOcean App Platform, Fly.io, Docker Compose on any VPS, or an Oracle Cloud Terraform stack, with the bearer token, workspace volume and secret storag

This page is for operators who want to run the core as a server process. Desktop users never need it, because the desktop app already runs a core in-process.

OpenHuman is a desktop app, but its Rust core (`openhuman-core`) is also a headless JSON-RPC server that you can host in the cloud. Hosting the core separately is useful for:

* Reaching the same core from several devices.
* Internal testers without a local Rust toolchain.
* Long-running cron jobs and webhooks that should outlive a laptop session.

This guide covers five deploy paths, easiest first:

1. [DigitalOcean App Platform: one-click](#1-digitalocean-app-platform-one-click)
2. [DigitalOcean App Platform: manual via doctl](#2-digitalocean-app-platform-manual-via-doctl)
3. [Any VPS via Docker Compose](#3-any-vps-via-docker-compose)
4. [Fly.io](#4-flyio)
5. [Oracle Cloud Infrastructure: Terraform on Always Free](#5-oracle-cloud-infrastructure-terraform-on-always-free)

Every path deploys a single container running `openhuman-core serve` on port `7788`. Public hosts should sit behind the provider's TLS, for example `https://core.example.com/rpc`. Private-only hosts on localhost, RFC1918 networks or tailnets such as Tailscale can use plain HTTP, for example `http://100.x.x.x:7788/rpc`, when the core is not reachable from the public internet. The desktop app can talk to a remote core directly. **Settings > Core connection** saves the RPC URL and bearer token, so you don't need an environment file on the desktop.

***

## Remote UI choices

The supported remote setup is core remote, UI local. Run `openhuman-core` on a Linux server and point a desktop client at its RPC URL. The deployed core does not serve the full UI as a production web app yet. Desktop-only features still need the desktop app: tray controls, native deep links, the native iMessage scanner, OS keychain integration and window and screen features.

For a browser UI on a private server today, use the Vite web build as a development and preview surface against the remote core:

```bash
# On the server, run the core with an explicit token.
export OPENHUMAN_CORE_HOST=0.0.0.0
export OPENHUMAN_CORE_PORT=7788
export OPENHUMAN_CORE_TOKEN="$(openssl rand -hex 32)"
openhuman-core serve

# In another shell on the server, serve the UI only on loopback.
pnpm --dir app dev -- --host 127.0.0.1 --port 1420
```

Then tunnel both ports from your workstation:

```bash
ssh -L 1420:127.0.0.1:1420 -L 7788:127.0.0.1:7788 user@server
```

Open `http://127.0.0.1:1420`, choose the remote/core option on the first-run screen, and enter `http://127.0.0.1:7788/rpc` plus the `OPENHUMAN_CORE_TOKEN` value from the server.

If you serve the browser UI from a non-loopback origin, add that exact origin to the core's CORS allowlist:

```bash
export OPENHUMAN_CORE_ALLOWED_ORIGINS="https://openhuman-ui.example.com"
```

Loopback Vite origins such as `http://127.0.0.1:1420` and `http://localhost:1420` are allowed automatically. Public `http://` origins are not recommended because every RPC call carries the bearer token.

***

## The bearer token

Every `/rpc` call carries `Authorization: Bearer <token>`. The core can load that token in two ways at startup:

1. **`OPENHUMAN_CORE_TOKEN` environment variable**: pre-seeded by the caller (Tauri shell, Docker, App Platform, systemd unit, …). The core uses this value as-is and **never** writes a file.
2. **`{workspace}/core.token` file**: generated by the core on first boot *only when `OPENHUMAN_CORE_TOKEN` is unset*. Standalone `openhuman-core run` uses this so CLI clients can `cat` the file.

For any remote or Docker deploy, always set `OPENHUMAN_CORE_TOKEN`. Do not rely on `core.token` in a container. Ephemeral filesystems lose it on redeploy, and a client reading the file from outside the container gets a stale or empty value. The two paths are mutually exclusive on purpose. Mixing them is the most common cause of "the dashboard gets 401 after I redeployed".

To check what the running core is using, run [`scripts/print-core-token.sh`](https://github.com/tinyhumansai/openhuman/blob/main/scripts/print-core-token.sh) on the host (or inside the container with `docker compose exec`):

```bash
scripts/print-core-token.sh --where     # prints 'env' or 'file:/path'
scripts/print-core-token.sh --redact    # first 8 hex chars + '…' (safe for logs)
scripts/print-core-token.sh             # full value (pipe straight into a client)
```

The desktop app's first-run picker and **Settings > Core connection** both have a **Test connection** button next to the Core RPC URL and token fields. It sends `core.ping` to the URL you typed with the token you typed, and reports one of three results before anything is saved: connected, auth failed or unreachable.

***

## What you need before you start

| Setting                               | Required               | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENHUMAN_CORE_TOKEN`                | yes                    | Bearer token clients send to `/rpc`. Generate with `openssl rand -hex 32`. **Anyone with this token can drive the core.**                                                                                                                                                                                                                                                                                                                                                  |
| `BACKEND_URL`                         | yes                    | Tinyhumans backend the core talks to (`https://api.tinyhumans.ai` for prod).                                                                                                                                                                                                                                                                                                                                                                                               |
| `OPENHUMAN_APP_ENV`                   | no                     | `production` or `staging`. Defaults to `production`.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `OPENHUMAN_KEYRING_MASTER_KEY`        | yes, if no OS keychain | 64 hex characters (`openssl rand -hex 32`). The `encrypted_file` keyring is now the default even when `OPENHUMAN_APP_ENV` is unset. Inject the key from your secret manager; **losing it orphans every stored secret.**                                                                                                                                                                                                                                                    |
| `OPENHUMAN_KEYRING_MASTER_KEY_FILE`   | alternative            | Path to a file holding the same value, for Docker/Kubernetes secret mounts. Set one of the two, not both. Without either, `encrypted_file` needs an OS keychain.                                                                                                                                                                                                                                                                                                           |
| `OPENHUMAN_SECRETS_UNATTENDED_UNLOCK` | no                     | `1` lets the host unlock encrypted config fields (provider API keys) without a person approving "Unlock configuration secrets", which nobody can answer on a server. Honoured only together with one of the two master-key settings above. Same as `[secrets] unattended_unlock = true`. See [OS keyring and secret storage](https://tinyhumans.gitbook.io/openhuman/features/privacy-and-security/os-keyring-and-secret-storage.md#unattended-unlock-on-a-headless-host). |
| `OPENHUMAN_CORE_HOST`                 | no                     | Defaults to `0.0.0.0` in the container.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `OPENHUMAN_CORE_PORT`                 | no                     | Defaults to `7788`.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `RUST_LOG`                            | no                     | `info` is fine; `debug` for triage.                                                                                                                                                                                                                                                                                                                                                                                                                                        |

The running container exposes these endpoints:

| Endpoint                                      | Auth                                                                                                                                                                                                              |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /health`                                 | None. The liveness probe every deploy path's healthcheck uses.                                                                                                                                                    |
| `GET /`                                       | None. Info page naming the other routes.                                                                                                                                                                          |
| `GET /schema`                                 | None. Read-only schema discovery.                                                                                                                                                                                 |
| `POST /rpc`                                   | The bearer token. This is the executable surface.                                                                                                                                                                 |
| `GET /events`                                 | Exempt from the header check, because a browser `EventSource` cannot set headers, but the handler enforces its own credential. Not an open stream.                                                                |
| `GET /oauth/mcp/callback`                     | Exempt from the bearer middleware: an external authorization server posts back here with no bearer. The one-time `state`, minted in `oauth_begin`, is the guard.                                                  |
| `GET /dev/connect`                            | Exempt from the middleware, guarded in the handler instead: a debug build or an explicit opt-in, a loopback `app` origin and `Host`, and no cross-site navigation. It should not be reachable on a deployed core. |
| `POST /v1/chat/completions`, `GET /v1/models` | The OpenAI-compatible surface, behind core's `http-server` gate. These accept the core bearer or an external provider key, so they are executable too, not just `/rpc`.                                           |

Only `/health`, `/` and `/schema` are truly unauthenticated. `/events`, `/oauth/mcp/callback` and `/dev/connect` skip the header check but each has its own guard. The two executable surfaces are `/rpc` and `/v1/*`.

The `OPENHUMAN_WORKSPACE` directory (`/home/openhuman/.openhuman` inside the container) holds the core's config, SQLite databases and skill state. Mount it on a persistent volume in every production deploy, or you will lose data on restart.

***

## 1. DigitalOcean App Platform: one-click

Click the button below to create an App Platform application from this repository's [`.do/app.yaml`](https://github.com/tinyhumansai/openhuman/blob/main/.do/app.yaml):

[![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/tinyhumansai/openhuman/tree/main)

Then, in the App Platform UI, **before the first deploy completes**:

1. Open the **Settings > App-Level Environment Variables** tab.
2. Replace the placeholder `OPENHUMAN_CORE_TOKEN` value with a strong secret (`openssl rand -hex 32`). Mark it encrypted.
3. If you are deploying staging, change `OPENHUMAN_APP_ENV` to `staging` and `BACKEND_URL` to `https://staging-api.tinyhumans.ai`.
4. Hit **Save**. App Platform redeploys with the new secret.

App Platform handles TLS, restart-on-crash, log streaming, and rolling redeploys on `git push` (set `deploy_on_push: true` in `.do/app.yaml` to opt-in).

> **Persistence:** App Platform Basic has no block storage. The core's workspace lives in the container's ephemeral filesystem and is lost on redeploy. For durable storage, attach a managed database or upgrade to a tier that supports volumes. The [Compose path](#3-any-vps-via-docker-compose) gives you persistent volumes out of the box.

***

## 2. DigitalOcean App Platform: manual via doctl

If you prefer not to click through the UI:

```bash
# One-time: install doctl and authenticate.
doctl auth init

# Edit .do/app.yaml - set OPENHUMAN_CORE_TOKEN to a real value (or pass it in
# at create time via --spec with envsubst). Then:
doctl apps create --spec .do/app.yaml

# Watch the build:
doctl apps list
doctl apps logs <app-id> --type build --follow
```

Update an existing app after editing the spec:

```bash
doctl apps update <app-id> --spec .do/app.yaml
```

***

## 3. Any VPS via Docker Compose

Works on any host with Docker Engine ≥ 24 and the Compose plugin. DigitalOcean Droplet, Hetzner, Linode, EC2, a home server.

Each production release publishes a multi-tagged image to GHCR:

```bash
docker pull ghcr.io/tinyhumansai/openhuman-core:latest          # tracks the latest prod cut
docker pull ghcr.io/tinyhumansai/openhuman-core:v<version>      # pinned by GitHub Release tag
docker pull ghcr.io/tinyhumansai/openhuman-core:<version>       # pinned by SemVer
```

Take `<version>` from the [latest release](https://github.com/tinyhumansai/openhuman/releases/latest). The two pinned tags are immutable and pushed per release; `:latest` is promoted only after the release publishes, so it never points at a cut that was rolled back (`.github/workflows/release-production.yml`).

The image is `linux/amd64`. arm64 hosts pull the standalone tarball attached to the same GitHub Release (`openhuman-core-<version>-aarch64-unknown-linux-gnu.tar.gz`) or build the image from source on an arm64 builder.

If you wrap a release tarball in your own image, match the builder it came from. The release matrix builds `aarch64` on `ubuntu-24.04-arm` and `x86_64` on `ubuntu-22.04` (`.github/workflows/release-production.yml`), so the `aarch64` binary needs glibc 2.39 or newer: `ubuntu:24.04` works, while `debian:bookworm-slim` ships 2.36 and fails at exec with `GLIBC_2.39' not found`. For `x86_64`, Ubuntu 22.04 or Debian 12 and newer.

Quick run with a published image:

```bash
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
```

Or use the in-repo Compose file, which builds the image locally from `Dockerfile`. To consume the published image instead, replace the service's `build:` block in `docker-compose.yml` with `image: ghcr.io/tinyhumansai/openhuman-core:latest`; leaving `build:` in place keeps building from source and merely retags the result.

```bash
# On the server:
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# Configure secrets:
cp .env.example .env
# Edit .env - at minimum:
#   BACKEND_URL=https://api.tinyhumans.ai
#   OPENHUMAN_CORE_TOKEN=<openssl rand -hex 32>
#   OPENHUMAN_APP_ENV=production

# Build and start:
docker compose up -d

# Verify:
docker compose ps
curl -fsS http://localhost:7788/health
```

### Headless install without Docker

If you can't run Docker on the host, grab the standalone CLI tarball attached to the latest [GitHub Release](https://github.com/tinyhumansai/openhuman/releases/latest):

```bash
# Pick the tarball that matches your host arch.
ARCH="$(uname -m)"
case "$ARCH" in
  x86_64)  TARGET=x86_64-unknown-linux-gnu  ;;
  aarch64) TARGET=aarch64-unknown-linux-gnu ;;
  *) echo "Unsupported arch: $ARCH"; exit 1 ;;
esac
VERSION=<version>   # the release you want, from the Releases page
curl -fsSL "https://github.com/tinyhumansai/openhuman/releases/download/v${VERSION}/openhuman-core-${VERSION}-${TARGET}.tar.gz" \
  | tar -xz -C /usr/local/bin
openhuman-core --version
```

Then run `openhuman-core serve` under your service manager of choice (systemd, supervisord, …) with the same environment variables documented above.

The tarballs are dynamically linked, so the host's glibc has to be at least as new as the builder's: `aarch64` needs 2.39 or newer (Ubuntu 24.04, Debian 13), `x86_64` wants Ubuntu 22.04 or Debian 12 and newer. Check with `ldd --version` on the host.

### Headless self-update contract

Headless deployments should treat `openhuman.update_apply` as the safe primitive: it downloads the release asset, writes it atomically next to the current binary, and returns. Nothing exits automatically.

`openhuman.update_run` follows `config.update.restart_strategy`:

* `self_replace` (default): stage the binary, publish an in-process restart request, and let the running core respawn itself.
* `supervisor`: stage the binary and return `restart_requested=false`. Your outer service manager must restart the process.

For long-running Linux services, set:

```toml
[update]
restart_strategy = "supervisor"
rpc_mutations_enabled = false
```

or the equivalent env vars:

```bash
OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY=supervisor
OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLED=false
```

Recommended `systemd` stance:

```ini
Restart=always
ExecReload=/bin/kill -HUP $MAINPID
```

Operator flow:

1. Call `openhuman.update_check` to discover a release.
2. Configure `restart_strategy = "supervisor"` under `[update]` in the core's `config.toml` (or set `OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY=supervisor`) so the core stages the new binary without trying to re-exec itself, then call `openhuman.update_apply` or `openhuman.update_run`. `restart_strategy` is a configuration setting, not an RPC parameter.
3. Restart the unit explicitly: `systemctl restart openhuman`.

If download or staging fails, the running binary is left in place and no restart is requested. If a staged binary proves bad after restart, roll back by restoring the previous binary from your package manager, image tag, or release artifact and restarting the supervisor again.

The Compose file ([`docker-compose.yml`](https://github.com/tinyhumansai/openhuman/blob/main/docker-compose.yml)) maps the core on `:7788`, mounts a named volume `openhuman-workspace` for persistence, and sets `restart: unless-stopped` so the core comes back after host reboots.

### Updating

```bash
git pull
docker compose build
docker compose up -d
```

For RPC-exposed production deployments, prefer leaving mutating update RPCs disabled (`OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLED=false`) and perform rollouts through your existing image tag or package-management flow instead.

### Logs

```bash
docker compose logs -f openhuman-core
```

### Rotating the bearer token

`OPENHUMAN_CORE_TOKEN` is the only thing standing between the public internet and full RPC access. Rotate it on a schedule and after any suspected leak:

```bash
# 1. Generate a new token and update the 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
rm /tmp/new-token .env.bak

# 2. Restart the container so the new value reaches the core process.
docker compose up -d --force-recreate openhuman-core

# 3. Confirm the running container is using the new token (redacted).
docker compose exec openhuman-core /bin/sh -c \
  'echo -n "$OPENHUMAN_CORE_TOKEN" | head -c 8; echo "…"'

# 4. Re-paste the new token on every desktop client, in
# Settings > Core connection. Clients that still hold the old token get
# HTTP 401 on the next /rpc call, which is expected rather than a regression.
```

For App Platform, do the same in **Settings > App-Level Environment Variables**. Edit the `OPENHUMAN_CORE_TOKEN` secret and let App Platform redeploy. There is no token file to delete. The environment variable is the only state.

### Putting it behind TLS

Use Caddy, nginx, or Traefik as a reverse proxy in front of `:7788`. A minimal `Caddyfile`:

```caddy
core.example.com {
  reverse_proxy localhost:7788
}
```

***

## Pointing the desktop app at a hosted core

Set this up in the app, not in a file. **Settings > Core connection** takes the core's RPC URL and bearer token. It has a **Test connection** button that sends `core.ping` with the values you typed, and it shows live reachability for the active core. The first-run picker accepts the same two fields.

Enter the server's URL and the token you set on it:

| Deployment              | URL to enter                   |
| ----------------------- | ------------------------------ |
| Public host behind TLS  | `https://core.example.com/rpc` |
| Private tailnet-only VM | `http://100.x.x.x:7788/rpc`    |

Saving stores the choice and restarts the app, so the normal startup checks run against the new core. A URL with no path is treated as the core's base, and `/rpc` is added for you. A `user:pass@host` URL is rejected, because the token field is the only way to give a credential.

Plain `http://` is accepted without a warning only for loopback and private-network hosts, including RFC1918 ranges and the Tailscale `100.64.0.0/10` range. A public `http://` host still saves, but the panel warns you.

{% hint style="warning" %}
A private address is not encryption. Over plain `http://`, every `/rpc` request carries the bearer token in cleartext, and that token is the only credential the core checks. Anyone who can observe the link can read it and replay it, and "private" covers a shared office LAN, a hotel network and a coffee-shop Wi-Fi subnet as readily as it covers your own machine. Treat plain HTTP as safe only on a link you control end to end, such as loopback or an encrypted overlay like Tailscale or WireGuard. Use HTTPS for anything else.
{% endhint %}

`VITE_OPENHUMAN_CORE_RPC_URL` in `app/.env.local` is only a build-time fallback. The saved panel value outranks it, so setting it will not move a desktop client onto a remote core.

### Troubleshooting: sign-in fails after OAuth on a cloud runtime

The symptom: OAuth in the browser completes ("close this and return to the app"), but the desktop then shows a sign-in error, while the same account signs in fine on the local (embedded) runtime.

The desktop app checks the fresh session token against the backend (`GET /auth/me`) itself and only then hands the credential to the core (`auth.set_credential`). On a cloud runtime that handoff goes to your server. The usual causes are:

* **Wrong RPC token or URL.** A token mismatch shows up as HTTP 401 on `/rpc`. Paste the token again (see "Rotating the bearer token") and check the URL.
* **Outdated core.** Older cores do not have `auth.set_credential`. The desktop still sends the older `auth_store_session` name through an alias, but a core older than that alias rejects the call. Update the server to a current release.
* **`BACKEND_URL` unset or wrong on the server.** The remote core no longer validates the session, but every backend call it makes for you (billing, teams, managed inference) still goes there. It must be `https://api.tinyhumans.ai` for production, or the staging URL.

Check the desktop log for `[session]` lines and the remote core log for `[credentials][set-credential]`. For these cases the desktop shows a specific message instead of a generic "try again".

### Headless sign-in

A cloud core has no browser to complete OAuth in. Get a credential elsewhere and hand it to the core at startup:

* `OPENHUMAN_BACKEND_API_KEY=<key>`: a TinyHumans API key. This is the recommended option. It has no user identity and nothing to expire.
* `OPENHUMAN_BACKEND_SESSION_TOKEN=<jwt>`: a session JWT with a subject claim.

Either one installs the credential only when the store has none of that kind. To rotate, clear it first (`openhuman-core auth clear_credential --kind api-key`). The same operation is available over RPC as `openhuman.auth_clear_credential`.

### Headless without a TinyHumans account

Custom cloud providers (`inference_url` and `api_key`, or an entry in `cloud_providers`) are built only when a backend session or TinyHumans API key exists. Without one, every turn fails with a `SESSION_EXPIRED: backend session not active` error. Runtimes you supply yourself are exempt, and `local-openai` is one of them. So any hosted OpenAI-compatible endpoint can run a headless core with no account:

1. Set `LOCAL_OPENAI_URL=https://<your endpoint>/v1` in the core's environment (`OPENHUMAN_LOCAL_INFERENCE_URL` also works and overrides it).
2. Store the endpoint's bearer key with `openhuman.config_update_local_ai_settings` (`runtime_enabled: true`, `opt_in_confirmed: true`, `api_key: "<key>"`).
3. Pin the workloads with `openhuman.config_update_model_settings`: `chat_provider`, `reasoning_provider`, `agentic_provider`, `coding_provider` (and `vision_provider`, `memory_provider`, `embeddings_provider` if you want them off the managed route) to `local-openai:<model-id>`, plus `default_model: "<model-id>"`. Those are the whole set the controller accepts.

`openhuman.inference_agent_chat_simple` is the quickest end-to-end check. Managed features (integrations, teams, hosted voice) still need a TinyHumans credential. See [Local models and bring your own key](https://tinyhumans.gitbook.io/openhuman/features/model-routing/local-and-byok-models.md).

### Secret storage in containers

The keyring backend is `encrypted_file` unless `OPENHUMAN_APP_ENV=dev`/`development` or an explicit backend override selects plaintext. Its master key comes from the OS keychain by default. A container normally has no keychain, so a provider-key write fails with `Failed to encrypt api_key` (`[keyring] set error ... master key unavailable`) until you supply `OPENHUMAN_KEYRING_MASTER_KEY` (64 hex characters) or `OPENHUMAN_KEYRING_MASTER_KEY_FILE` (a secret mount). Keep that key stable across restarts; losing it makes stored secrets unreadable. Older releases without these variables supported `OPENHUMAN_KEYRING_BACKEND=file`, which stored plaintext in `$OPENHUMAN_WORKSPACE/dev-keychain.json` (mode `0600`). On upgrade, the encrypted backend writes and reads back `secrets.enc` before removing that plaintext file. It also removes older `dev-keychain.json.migrated` copies when their entries match the decrypted store. Copies with different or unreadable contents remain for manual recovery; inspect them before removal.

Mount the key file without group or world write permission. The core rejects group-writable and world-writable files. Read-only group or world access may be accepted for container secret mounts, but any process that can read the file can decrypt the whole keyring. Restrict the mode where the mount is declared:

* Kubernetes: Secret volumes are root-owned, and `runAsUser` does not change the owner of a projected Secret. For a non-root core, use an init container running as root to copy the Secret into an `emptyDir`, `chown` the copy to the core UID, and `chmod 0400` it before the core starts. Mount the original Secret read-only in the init container and the `emptyDir` read-only in the core container. For example:

  ```yaml
  volumes:
    - name: master-key-secret
      secret:
        secretName: openhuman-master-key
        defaultMode: 0400
    - name: master-key
      emptyDir: {}
  initContainers:
    - name: prepare-master-key
      image: busybox:1.36
      command: ["sh", "-c", "cp /source/master.key /target/master.key && chown 10001:10001 /target/master.key && chmod 0400 /target/master.key"]
      volumeMounts:
        - name: master-key-secret
          mountPath: /source
          readOnly: true
        - name: master-key
          mountPath: /target
  containers:
    - name: openhuman
      securityContext:
        runAsUser: 10001
        runAsGroup: 10001
        runAsNonRoot: true
      env:
        - name: OPENHUMAN_KEYRING_MASTER_KEY_FILE
          value: /run/openhuman-master-key/master.key
      volumeMounts:
        - name: master-key
          mountPath: /run/openhuman-master-key
          readOnly: true
  ```

  Set the `emptyDir` medium and the core UID/GID to match the ownership applied by the init container. The `defaultMode: 0400` setting is important. For a direct non-root mount, also provide `fsGroup` (or equivalent group access) matching the core's group so kubelet can make the file readable; the resulting read-only `0440` mode is accepted. The init-container recipe above instead grants access by changing the copied file's owner. An equivalent setup is a secret volume whose `defaultMode` is `0400` and whose file is mounted with ownership matching the core's `runAsUser`/`runAsGroup`.
* Docker Swarm: set `mode: 0400` (with `uid`/`gid` for a non-root user) on the service's secret.
* A plain file: `chmod 600` it, owned by the user the core runs as.

***

## Named-volume ownership and the Docker entrypoint

Docker creates named volumes owned by `root:root`. The core runs as the non-root `openhuman` user (UID 10001), so its first write into `$OPENHUMAN_WORKSPACE` would fail with `Permission denied (os error 13)` if nothing fixed the ownership first.

The image ships a dedicated entrypoint at `/usr/local/bin/docker-entrypoint-core.sh` that:

1. Starts as `root`.
2. Runs `mkdir -p` + `chown openhuman:openhuman` on both `$OPENHUMAN_WORKSPACE` and `$HOME/.openhuman` (the directory `core.token` is written to when `OPENHUMAN_CORE_TOKEN` is unset).
3. Calls `exec gosu openhuman openhuman-core "$@"` to drop privileges and hand off to the binary.

This is idempotent. On a new volume the chown fixes the root-owned directory. On a volume that was already fixed, it does nothing. You don't need to run `docker volume rm` when upgrading from an older image.

The entrypoint is used only by the root `Dockerfile`. The E2E image (`e2e/docker-entrypoint.sh`) is unaffected.

***

## 4. Fly.io

[Fly.io](https://fly.io) suits `openhuman-core`. It handles TLS automatically, supports persistent volumes on all tiers, and can stop idle machines to cut costs.

### Prerequisites

* [flyctl](https://fly.io/docs/flyctl/install/) installed and authenticated (`fly auth login`)
* A Fly.io account

### Step 1: Launch the app

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

Fly.io finds the `Dockerfile` automatically. Choose a region close to your users and skip the first deploy when prompted. This generates a config file.

### Step 2: Configure `.fly/fly.toml`

The repo ships a template at [`.fly/fly.toml`](https://github.com/tinyhumansai/openhuman/blob/main/.fly/fly.toml). Fill in `<your-app-name>` and `<your-region>` with the values you chose during `fly launch`:

```toml
app = '<your-app-name>'
primary_region = '<your-region>'

[build]
  dockerfile = "Dockerfile"

[env]
  OPENHUMAN_CORE_HOST = "0.0.0.0"
  OPENHUMAN_CORE_PORT = "7788"
  OPENHUMAN_WORKSPACE = "/home/openhuman/.openhuman"
  RUST_LOG = "info"

[[mounts]]
  source = "openhuman_workspace"
  destination = "/home/openhuman/.openhuman"

[http_service]
  internal_port = 7788
  force_https = true
  auto_stop_machines = 'stop'
  auto_start_machines = true
  # min_machines_running = 0 fully stops the machine when idle (cheapest), but
  # the first request after idle pays a cold-start penalty (container boot +
  # Rust binary init, several seconds). Set to 1 to keep one machine warm.
  min_machines_running = 0
  processes = ['app']

  [[http_service.checks]]
    interval = "30s"
    timeout = "5s"
    grace_period = "10s"
    method = "GET"
    path = "/health"

[[vm]]
  memory = '1gb'
  cpus = 1
```

### Step 3: Create a persistent volume

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

Mount the workspace on a persistent volume, or data is lost on every redeploy.

### Step 4: Set secrets

```bash
# Required
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"

# Recommended for any publicly-reachable deployment:
fly secrets set OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLED="false"
fly secrets set OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY="supervisor"

# Optional: error reporting and analytics:
fly secrets set OPENHUMAN_CORE_SENTRY_DSN="https://<key>@o<org>.ingest.sentry.io/<project>"
fly secrets set OPENHUMAN_ANALYTICS_ENABLED="true"
```

Save the value of `OPENHUMAN_CORE_TOKEN`. You need it to connect the desktop app later. Anyone with this token can drive the core, so treat it like a password and rotate it with `fly secrets set OPENHUMAN_CORE_TOKEN="$(openssl rand -hex 32)"` after any suspected leak.

### Step 5: Deploy

```bash
fly deploy --config .fly/fly.toml
```

Verify the core is healthy:

```bash
curl -fsS https://<your-app-name>.fly.dev/health
```

### Step 6: Point the desktop app at the hosted core

In the desktop app, open **Settings > Core connection**, switch it to the remote core, and enter:

* URL: `https://<your-app-name>.fly.dev/rpc`
* Token: the value you set in Step 4

Press **Test connection** to confirm before saving. The first-run picker takes the same two fields. See [Pointing the desktop app at a hosted core](#pointing-the-desktop-app-at-a-hosted-core).

### Continuous deployment

To redeploy automatically on every push to `main`, add a workflow file at `.github/workflows/fly-deploy.yml`:

```yaml
name: Fly Deploy
on:
  push:
    branches:
      - main
    paths:
      - "src/**"
      - "Cargo.toml"
      - "Cargo.lock"
      - "Dockerfile"
      - ".fly/fly.toml"
      - "scripts/docker-entrypoint-core.sh"
jobs:
  deploy:
    name: Deploy openhuman-core
    runs-on: ubuntu-latest
    concurrency: deploy-group
    steps:
      - uses: actions/checkout@v4
      # Pin the Fly action to a tagged release (or a full commit SHA) rather
      # than `@master`. Tracking a moving branch trusts every future commit
      # pushed there, including any made by a compromised maintainer account.
      - uses: superfly/flyctl-actions/setup-flyctl@1.5
      - run: flyctl deploy --remote-only --config .fly/fly.toml
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
```

Generate a deploy token with `fly tokens create deploy` and add it as a repository secret named `FLY_API_TOKEN`.

### Updating

```bash
fly deploy --config .fly/fly.toml
```

For version-pinned deployments, update the image tag in `.fly/fly.toml` and redeploy:

```toml
[build]
  image = "ghcr.io/tinyhumansai/openhuman-core:v<version>"
```

### Logs

```bash
fly logs --config .fly/fly.toml
```

### Known issue: user ID mismatch on volumes

If you switch between building from the `Dockerfile` (which creates the `openhuman` user at UID 10001) and pulling the pre-built GHCR image (which uses UID 1000), files already on the persistent volume belong to the old UID. The core then fails at startup with `Permission denied (os error 13)`.

The same thing happens to a Docker named volume that outlives an image upgrade, and to any workspace that a root `docker exec` wrote into. `docker exec` does not run the entrypoint, so it runs as root and leaves a `root:root` `config.toml` behind. The core writes that file with mode 0600, so the runtime user then cannot open it at all.

`scripts/docker-entrypoint-core.sh` repairs this automatically. On every start it recursively chowns the workspace and skips entries that already have the right owner. If the repair cannot run (for example `cap_drop: ALL` without `cap_add: CHOWN`), the entrypoint refuses to start and prints the exact `chown` to run. Otherwise you would get a container that answers `/health` with 200 while every config RPC returns `Permission denied (os error 13)`. Look for `[docker-entrypoint] pre-heal` and `FATAL` lines in the container log.

To fix an older container, SSH in and re-own the workspace:

```bash
fly ssh console --config .fly/fly.toml
chown -R openhuman:openhuman /home/openhuman/.openhuman/
exit
fly machine restart --config .fly/fly.toml
```

The Docker equivalent derives the ids from the container instead of hard-coding them, so it stays correct whichever image you run:

```bash
docker exec -u 0 openhuman-core sh -c \
  'chown -Rh "$(id -u openhuman):$(id -g openhuman)" /home/openhuman/.openhuman'
docker restart openhuman-core
```

To see which UID owns what before repairing, ask about the runtime user explicitly. `docker exec` defaults to root, so a bare `id` would be misleading:

```bash
docker exec openhuman-core sh -c 'id openhuman; ls -ln /home/openhuman/.openhuman/config.toml'
```

***

## Smoke test

Two smoke checks cover the cloud deploy path:

* `docker-image` sets `OPENHUMAN_CORE_TOKEN` and mounts no volume. It covers the DigitalOcean App Platform path (`.do/app.yaml`), where the token is always set and no persistent volume is used.
* `docker-volume-permissions` omits `OPENHUMAN_CORE_TOKEN` and mounts a fresh anonymous volume at `/home/openhuman/.openhuman`. It reproduces the volume ownership failure and asserts that `/health` returns 200 and that `Permission denied (os error 13)` is absent from the logs.

Run the smoke check locally:

```bash
docker build -t openhuman-core:smoke .

# Optional: tune build profile and Cargo parallelism.
# Keep CARGO_BUILD_JOBS=1 on constrained builders; raise it on larger machines.
docker build --build-arg CARGO_PROFILE=release --build-arg CARGO_BUILD_JOBS=4 -t openhuman-core:release .

# Token-set path (App Platform):
docker run -d --name oh-smoke -p 7788:7788 \
  -e OPENHUMAN_CORE_TOKEN=smoke-test-token \
  openhuman-core:smoke
curl -fsS http://localhost:7788/health
docker rm -f oh-smoke

# Fresh-volume / no-token path (Docker Compose, VPS):
docker volume create oh-vol-test
docker run -d --name oh-vol-smoke -p 7789:7788 \
  -v oh-vol-test:/home/openhuman/.openhuman \
  openhuman-core:smoke
curl -fsS http://localhost:7789/health
docker rm -f oh-vol-smoke
docker volume rm oh-vol-test
```

***

## 5. Oracle Cloud Infrastructure: Terraform on Always Free

A community-maintained Terraform stack runs the headless core on OCI's Always Free tier: an Ampere A1 VM in a private subnet running the release binary in a container, a flexible load balancer that forwards only `/rpc`, `/health` and `/events`, secrets in OCI Vault read by the VM's instance principal, OCI Generative AI as the model provider through the `local-openai` route above, and an Autonomous Database that agents reach through Oracle's managed Database Tools MCP Server once an operator registers a user access token for that server (the stack's post-apply step; the MCP server authenticates users, not the VM's instance principal).

Repository and run book: <https://github.com/kamelhar/openhuman-oci>. Like the Fly and DigitalOcean recipes, it sets `OPENHUMAN_CORE_TOKEN`, mounts the workspace on persistent storage, and keeps the core off the public internet except through the load balancer.

***

## See also

* [Privacy and security](https://tinyhumans.gitbook.io/openhuman/features/privacy-and-security.md): the trust model a server-hosted core inherits.
* [OS keyring and secret storage](https://tinyhumans.gitbook.io/openhuman/features/privacy-and-security/os-keyring-and-secret-storage.md): why a container needs a keyring master key.
* [Local models and bring your own key](https://tinyhumans.gitbook.io/openhuman/features/model-routing/local-and-byok-models.md): running a headless core with no TinyHumans account.
* [Building the Rust core](https://tinyhumans.gitbook.io/openhuman/developing/building-rust-core.md): compiling the binary a non-Docker host runs.
* [Architecture](https://tinyhumans.gitbook.io/openhuman/developing/architecture/architecture.md): what the core owns versus the shell.
