Skip to content
relay_
Get started
[ get started ]

Run your own.One command.

Relay runs on your own computer, with your own database and your own keys. Nothing is hosted for you, and nothing you index leaves your machine except the passages sent to the two model services. Most of the setup time is clicking through Google Cloud once.

01

Before you start

02

Install and run

run it without installing anything
npx relay-workspace

The first run asks for your keys (next step), starts Postgres and Qdrant in Docker, creates the database tables, and starts Relay at http://localhost:3000. Prefer a permanent command?

or install it once
npm install -g relay-workspacerelay

03

The setup

Relay reads your Workspace through a Google Cloud project that you own, so nobody else ever holds access to your data. The setup prints these four steps with links. You do them once.

  1. Create a project in Google Cloud, then enable the Drive, Docs, Gmail, Calendar and Sheets APIs.
  2. Set up the OAuth consent screen as External with publishing status Testing, and add your own Google account under Test users.
  3. Create an OAuth client of type Web application with the authorized redirect URI http://localhost:3000/api/auth/google/callback.
  4. Copy the client ID and client secret. Then create a Hugging Face token (Read) and a Groq API key.

Paste each key when asked. Hugging Face and Groq keys are tested on the spot, so a typo is caught before anything starts. Relay also generates its own encryption key and database passwords and keeps them in ~/.relay/.env. Back that file up: the encryption key protects your stored Google access, and without it you would have to reconnect.

04

Connect Google

Open /connections, connect Drive, and press Sync. When it finishes, ask a question on /chat. Gmail is opt-in: you pick a label or a date range first, because Relay never indexes a whole mailbox by default. Once you trust it, switch on auto-sync so sources keep themselves fresh.

Drive and Calendar refresh when you press Sync, and Gmail is checked every five minutes. Google can only push change notifications to a public HTTPS address, which a computer at home does not have.

05

Commands

Relay commands
relayStart Relay. The first run walks you through setup.
relay setupEnter or change your Google, Hugging Face and Groq keys.
relay doctorCheck that Docker, both databases, the job runner and your keys are working.
relay stopStop Postgres and Qdrant. Your data is kept.
relay --openStart Relay, then open it in your browser.

Relay listens only on 127.0.0.1 and has no login, because it is built for one person on one computer. Do not expose it to a network. The security page explains what protects it and what does not.

06

If it breaks

  • Open Docker Desktop and wait until it reports that it is running, then run relay again. Relay never starts Docker itself.
  • Stop whatever is using it, or set PORT in ~/.relay/.env. If you change it, add the new redirect URI (with that port) to your OAuth client in Google Cloud.
  • Expected. The OAuth app you created is in Testing mode. Choose Advanced, then Go to your app. It is safe because you created the app and only you are on its test-user list.
  • The Google account you are signing in with is not on the consent screen's test-user list. Add it under Google Auth Platform, Audience, Test users.
  • The redirect URI in your Google OAuth client has to match the one the setup printed exactly, including the port. Copy it again from the setup, or run relay setup to see it.
  • That is Gmail's per-user rate limit. Relay retries with backoff for about a minute and keeps partial progress, so press Sync again shortly and it continues from where it stopped.
  • For apps in Testing mode Google expires refresh tokens after seven days. Open Connections and reconnect the account.
  • Your keys are in ~/.relay/.env. Your indexed text is in two Docker volumes on this computer. To delete everything, run relay stop, then remove the volumes in Docker Desktop (their names start with relay_) and delete the ~/.relay folder. Disconnecting an account on the Connections page also deletes its indexed content and revokes Relay's access at Google.
  • Run relay doctor. It checks every part Relay depends on and tells you which one is failing and what to do about it.

Building from source instead

terminal
git clone https://github.com/jabluetooth/relay relaycd relaynpm installnpm run build:packagenode bin/relay.mjs