GET YOUR TEAM READY

Your server.
Your AI workspace.

Build Yaoyao AI v0.4.4 from source with Docker. Connect your existing Hermes service and share one AI workspace across Web, macOS, iOS, and Android.

v0.4.4 release and downloads

Docker ComposeBuild from source

01 / Prerequisites

Three things before you begin.

Docker + Compose

Install Docker Engine with Compose, or Docker Desktop. The product Dockerfile provides Node.js for the build.

A reachable Hermes service

Prepare a Hermes Dashboard / Gateway that the container can reach, usually on port 9119.

Yaoyao product source

Run the following commands in the product source directory containing compose.yaml and docker.env.example.

Get the product source

02 / Connection settings

Give Yaoyao a connection to Hermes.

Copy the environment template, then edit docker.env for your network. These are the defaults for local access.

01 · shell

cp docker.env.example docker.env

docker.env

HERMES_YAOYAO_UPSTREAM=http://host.docker.internal:9119
HERMES_YAOYAO_BIND_ADDRESS=127.0.0.1
HERMES_YAOYAO_PUBLISHED_PORT=15300
HERMES_YAOYAO_ALLOWED_HOSTS=

HERMES_YAOYAO_UPSTREAM

A Hermes address reachable from the container.

HERMES_YAOYAO_BIND_ADDRESS

Defaults to 127.0.0.1; use 0.0.0.0 for trusted LAN access.

HERMES_YAOYAO_PUBLISHED_PORT

Published host port; defaults to 15300.

HERMES_YAOYAO_ALLOWED_HOSTS

Allowed domain names, separated by commas.

Docker Desktop can reach the host via host.docker.internal. On Linux, Compose maps the host gateway, and Hermes must listen on an address reachable from the container. For remote Hermes, enter its reachable service address.

03 / Build and launch

Build it. Then meet your team.

Validate the Compose configuration, build the image, and start the service. The first build downloads dependencies and may take a few minutes.

02 · shell

docker compose --env-file docker.env config --quiet
docker compose --env-file docker.env up -d --build
docker compose --env-file docker.env ps

Open http://127.0.0.1:15300 by default. Create your administrator account, then save your Hermes credentials in system settings.

Connect iOS and Android to the same Yaoyao server; iOS supports a password or mobile sign-in QR code. Use a server IP or HTTPS domain reachable from your phone, not port 9119 or the phone’s own 127.0.0.1. See the release page for Android installation requirements.

Install the iOS beta via TestFlight Download Android 1.3 (162)

04 / Verify the service

Check the connection. Try the experience.

These commands use the default port. Update the URLs if you changed the published port.

03 · shell

curl --noproxy '*' --fail http://127.0.0.1:15300/healthz
curl --noproxy '*' --fail http://127.0.0.1:15300/readyz
docker compose --env-file docker.env logs --tail=100 web

/healthz

Checks the Yaoyao Web service itself.

/readyz

Checks whether the Hermes upstream is ready.

Sign in, create a role, send a message, and upload and download an attachment. Check your history on Web, iOS, or Android with the same account to complete the test.

05 / Data and updates

Keep the work going. Keep your data.

Accounts, chats, files, and keys are stored in the yaoyao-data named volume at /home/node/.yaoyao inside the container. Replacement containers reuse this volume.

Before upgrading, stop Web and back up the entire data directory to a new, separate location. Preserve permissions and encryption keys, then restart the service. A single database file is not a complete backup.

Get the updated source from GitHub Releases, then rebuild the image and recreate the container. Check the release notes for companion client requirements.

04 · shell

docker compose --env-file docker.env up -d --build
docker compose --env-file docker.env ps

docker compose down preserves volumes. Adding --volumes deletes the data; use it only when intentionally clearing the deployment.

06 / Common questions

A few things you might be wondering.

Does the container include Hermes?

Yaoyao connects to a separately managed Hermes service on port 9119. It does not need the Hermes filesystem or Docker socket mounted into the application.

How do I enable LAN or public access?

For a trusted LAN, publish on 0.0.0.0 and use the server IP. For public access, configure HTTPS on your reverse proxy and add the domain to the allowed hosts.

Web is healthy, but Hermes is not ready?

Check the upstream URL, Hermes listening address, and container network. If Hermes requires authentication, save the correct credentials in Yaoyao system settings.

Does data leave my server?

Your server persists the application data. Models, tools, or voice providers may use remote services; data flow depends on the configuration you choose.

What is the product license?

Yaoyao uses the Apache-2.0 license. Refer to LICENSE in the product source for the applicable use and distribution terms.

Your server.Your AI workspace.