Self-hosting

Suzo is being built for a hosted iPhone experience. Self-hosting is an optional advanced path. The current source is a standalone development service with one paired phone; it does not provide shared accounts or turnkey public onboarding.

The source repository is currently private. These instructions apply to developers with authorized source access and a provisioned native build. They do not offer a public download or source license.

Requirements

Use Node.js 22.13+, a persistent data directory, and a stable HTTPS origin with WebSocket forwarding. Native builds require macOS, Xcode 26.5+, and a physical iPhone running iOS 18+. Background ringing needs an Apple development team and push-enabled provisioning.

cp .env.example .env
cd server
npm ci
npm run build
npm start

Set PUBLIC_BASE_URL to your trusted HTTPS origin. The default service port is 8787. Keep keys, pairing files, runtime state, and signing material out of source control and container build contexts.

Container and routing

The calling service has its own container in the private application repository. Run it as the unprivileged user and mount persistent storage at /data with ownership appropriate for UID 1000. The website repository contains only static website containers and cannot run the calling service.

Route https://api.suzo.app to the service on port 8787 with HTTPS and WebSocket upgrades. Set PUBLIC_BASE_URL=https://api.suzo.app for that deployment. Self-hosted installations use their own trusted HTTPS origin. Marketing and the blog live separately at https://suzo.app; documentation lives at https://docs.suzo.app. /mcp, /v1/*, /voice/*, /health, and /setup/* belong to the API origin. Neither website proxies those routes, and unknown API paths never return the homepage.

Pair and configure

Run the native application’s Xcode project with your signing team. If changing the bundle identifier, update its APNs topic together. Pair using the HTTPS service URL and the expiring private code in the server data directory.

Add the agent from the phone and follow MCP setup. Configure provider keys in Settings, or choose local speech. Keep helper configuration private.

Back up and update

Back up the complete data directory together with the vault key. Keep APNs key material separate from the image. SQLite and the vault are single-instance state: use one replica, stop-first deployment, and maintenance only after active calls have ended.

Verify health, authentication, MCP discovery, packaged guides, helper connectivity, and persistence after restart. Local checks or an unsigned native build do not prove physical ringing or audible provider audio.