Documentation

Set up Chez Maurice

Run the server on your Mac, connect the apps, and reach it from anywhere. Fifteen minutes, no Docker, no cloud account.

1 · Getting started 2 · Connect an app 3 · Reach it from anywhere Config reference Troubleshooting

1 · Get the server running

The server is the engine — it holds your data and gardens and talks to the models. It runs on a Mac you own. Two ways to get it:

Option A — the installer (simplest)

Download Chez Maurice Server (a notarized .pkg) and open it.
It installs a background service that starts automatically and listens on http://localhost:3001. Config lives in ~/.maurice/.

Option B — from source

Needs Bun.

git clone https://github.com/ckemmler/chez-maurice.git
cd chez-maurice/server
bun install
bun run index.ts            # → http://localhost:3001

First run — create your household

Open http://localhost:3001/admin in a browser. You'll be sent to a one-time setup page — create the admin account.
From /admin, add a model:
- Local & private: run Ollama — your installed models are detected automatically.
- Cloud: paste an Anthropic, OpenAI or Mistral API key. Keys are stored only in the local database, never in the repo.
Add the rest of your household from /admin (each member gets their own space and a PIN).

2 · Connect an app

Install the Mac or iOS app (TestFlight, or build from app/ in Xcode). On first launch it asks for a server address:

On the same Mac running the server, enter http://localhost:3001.
From any other device (your phone, another Mac), you first need a reachable address with HTTPS — that's the next section.

Then tap your member, enter your PIN, and you're in.

3 · Reach it from anywhere

Phones can't reach localhost, and the apps expect HTTPS. So the server needs a real hostname with a valid certificate. Two good ways — pick one. Both keep your data on your Mac; they only create a private, encrypted path to it.

Tailscale recommended

A private network between your own devices. Maurice serves HTTPS directly on your tailnet name.

Install Tailscale on the Mac and sign in. Note its name, e.g. mac-mini.tail1234.ts.net.
Get a TLS cert for that name:
```
tailscale cert mac-mini.tail1234.ts.net
```
It writes mac-mini.tail1234.ts.net.crt and .key.

Point Maurice at them — add to ~/.maurice/.env (create it):

MAURICE_TLS_CERT=/Users/you/mac-mini.tail1234.ts.net.crt
MAURICE_TLS_KEY=/Users/you/mac-mini.tail1234.ts.net.key
MAURICE_PUBLIC_HOST=mac-mini.tail1234.ts.net

Restart the server (maurice restart, or re-run bun run index.ts).
Install Tailscale on your phone (same account), and pair the app to
https://mac-mini.tail1234.ts.net:3001.

Cloudflare Tunnel

Reach it over the public internet on a domain you own. Cloudflare terminates TLS, so Maurice can stay plain-HTTP on localhost.

Install cloudflared and log in:

brew install cloudflared
cloudflared tunnel login

Create a tunnel and route a hostname to it:

cloudflared tunnel create maurice
cloudflared tunnel route dns maurice \
  maurice.example.com

Configure ~/.cloudflared/config.yml:

tunnel: <tunnel-id>
credentials-file: ~/.cloudflared/<id>.json
ingress:
  - hostname: maurice.example.com
    service: http://localhost:3001
  - service: http_status:404

Run it (keep it alive with launchd for production):
```
cloudflared tunnel run maurice
```
Pair the app to https://maurice.example.com.

Which one? Tailscale is simplest and keeps everything private to your own devices — ideal for a household. Use a Cloudflare Tunnel if you want a public domain (e.g. to share a room with someone outside your tailnet). You can run both.

Config reference

Settings go in ~/.maurice/.env (installed server) or the repo-root .env (from source). Model API keys are not here — set those in /admin so they stay in the database.

Variable	What it does
`PORT`	Server port. Default `3001`.
`MAURICE_TLS_CERT` `MAURICE_TLS_KEY`	Paths to a cert + key to serve HTTPS. If unset, the server runs plain HTTP on localhost.
`MAURICE_PUBLIC_HOST`	The host the apps reach the server on (used in its self URL). Default `localhost`.
`GARDEN`	Which garden the web engine serves (folder under `web/gardens/`). Default `demo`.
`MAURICE_GARDENS_DIR`	Absolute gardens root in production.

Troubleshooting

The app says it can't connect

Check the server is up: curl -k https://your-host:3001/api/health should return {"status":"ok"}.
From a phone, the address must be the Tailscale/Cloudflare host, not localhost.
Make sure the Mac isn't asleep — a server that sleeps drops the connection. On a Mac mini, enable “Prevent automatic sleeping when the display is off.”

Maurice replies “Echo mode — no API key configured”

No usable model. Open /admin and either add a cloud API key or start Ollama with a model pulled, then make sure your member is allowed to use it.

Push notifications don't arrive

Push needs an APNs key in ~/.maurice/secrets/ and, for TestFlight/App Store builds, APNS_PRODUCTION=1.