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. To stand the server up from scratch, follow the self-hosted setup guide, which walks through running the Docker stack, securing it, connecting Contextify, and verifying search and recall.

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

Open Settings → Cloud

Choose Contextify Cloud Self-Hosted.
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.
Paste the API key

The app validates the self-hosted server and API key before replacing the saved hosted connection on this Mac.
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 self-hosted server runs the contextify-cloud Docker stack with Docker Compose and PostgreSQL, with SELF_HOSTED=true. The self-hosted setup guide covers standing it up end to end: cloning the public source, setting your secrets, bringing up the stack, and creating the owner account.

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