Docs / Self-hosted / Connect client

Self-hosted Cloud

Connect to your own Contextify Cloud server.

Self-hosted Cloud is for users who want the sync API and dashboard on infrastructure they control. The client setup is simple once the server exists: use the server URL and a sync-capable API key.

This page covers connecting a client to an existing self-hosted server. Full server bootstrap, backups, updates, and first-owner setup are separate operations docs.

What you need

Server URL

Use the client-reachable URL for the server, including the correct scheme and port. For Tailscale or VPN-only setups, this may be a tailnet hostname rather than an internet-public address.

API key

Create a sync-capable API key from the self-hosted dashboard. Search-only keys are not enough for upload.

Health check

The server should answer at /api/v1/health before you configure a client.

Confirm the server is healthy

From a device that can reach the server, hit the health endpoint:

curl -s https://your-server.example.com/api/v1/health

A healthy self-hosted server returns:

{"status": "ok", "self_hosted": true}

self_hosted is true on a self-hosted deployment and false on hosted Contextify Cloud. Use it to confirm the URL you are pointing at is the server you expect.

Connect the Mac app

  1. Open Settings → Cloud

    Choose Contextify Cloud Self-Hosted.

  2. Enter the server URL

    Use the same hostname covered by the server's TLS certificate. For Tailscale HTTPS, that is usually a .ts.net hostname.

  3. Paste the API key

    The app validates the self-hosted server and API key before replacing the saved hosted connection on this Mac.

  4. Save and check status

    The Cloud tab should show the self-hosted provider, server URL, and sync status. If the app is still ingesting a large local history, sync may wait until local processing finishes.

Connect from the CLI

Prefer the interactive prompt when you can, because it avoids putting an API key in shell history. 

contextify cloud setup --url https://your-server.example.com
contextify cloud status --json
contextify cloud sync

For headless setup, --key is supported. Treat command transcripts as sensitive if they include a real key. 

contextify cloud setup --url https://your-server.example.com --key ctx_REDACTED --no-input

If your self-hosted server is reachable only inside a VPN or tailnet, run these commands from a device on that network.

Server setup, briefly

The current self-hosted server path uses the contextify-cloud source checkout, Docker Compose, PostgreSQL, and a generated homeserver setup script. The server runs with SELF_HOSTED=true.

The supported HTTPS shape is a stable hostname on your network, TLS terminating in front of the API, and the API proxying to its loopback container port. HTTP-only mode exists for validation on trusted networks, not as the preferred long-term setup.

Common first failure

The most common self-hosted failure is target-specific reachability: the Mac has internet, but it cannot resolve or connect to the self-hosted hostname.

Read the TLS, VPN, and Tailscale guide

Read about ingestion and syncing if the connection is healthy but Cloud has not caught up yet.

Last updated: May 6, 2026