Getting started with relai

This guide takes you from knowing nothing to having captured your first pin. Follow it top to bottom. It takes about ten minutes, and most of that is installing a browser extension. You do not need to know how to code, and you do not need to change anything on your website.

Before you start

You need three things:

• An email address you can receive mail at.
• Chrome, Firefox, or Safari.
• The web address of the site you want to give feedback on, for example https://app.acme.com. It can be a live site, a staging site, or a site running on your own machine.

relai works through a small browser extension that you install once. It covers every site you use it on, and it does not require a developer to set up.

Step 1: Create your account

1. Go to staging.relai.team/signup.
2. Either click Google or GitHub, or use the email form below the or with email divider. It asks for Name, Work email and Password (at least 6 characters).
3. Tick the box agreeing to the terms and privacy policy.
4. Click Create account.
5. relai emails you a 6-digit code and the card changes to Check your email. Type the code into the Verification code box and click Verify and continue.

If no code arrives, click Resend code. If you mistyped your address, click Use a different email and start again.

Step 2: Name your workspace

After you verify, one card asks you to Name your workspace.

A workspace is the shared space that holds your team’s sites, pins and people. Everyone you invite later joins this same workspace, so name it after your company rather than after yourself.

Type the name in the Workspace name box and click Continue. That opens All pins. Owners and Admins find a short list of next steps there: Create your workspace (already ticked), Add your website, Set up this browser to drop pins and Invite your team, each with one button.

Step 3: Add your website

Now done from the short list on All pins, after sign-up. Owners and Admins add websites.

Members ask an admin: on the empty Pins page, or in Settings under Sites, they click Ask an admin to add a site, type the address and click Ask. Every Owner and Admin gets a note in their bell with an Add website button, which opens this wizard with the address filled in.

Click Add website. It opens a three-part wizard. You can see which part you are on from the rail across the top: Site, Browser, Enable.

The first screen asks What’s your site’s URL? Type the web address of the site you want to pin on. There is a second, optional box for a friendly Site name, useful once you have several sites. Click Continue.

Use the address people actually visit. acme.com and www.acme.com are the same website to relai, so either works. Other addresses on the same domain, such as app.acme.com, are websites of their own and are added separately. If you get it slightly wrong, relai notices which address you really enable it on in Step 5 and registers that one instead.

Step 4: Install the extension and connect it

The wizard moves to the Browser step. It asks one thing at a time, so what you see depends on what you already have. If relai isn’t installed yet, it opens on Install the relai extension with a single button for the browser you’re actually using: Add relai to Chrome or Add relai to Firefox. Click it, install, and come back to this tab.

The step-by-step version for each browser is below if you’d rather follow that. If the extension is already installed, the wizard skips straight past this to Connect relai to your account.

While you’re at the store, the wizard shows Waiting for the extension… and keeps checking on its own. One quirk to expect: a page that was already open before you installed something usually can’t see it until the page reloads. That’s the browser’s rule, not relai’s. If the wizard is still waiting a few seconds after you’ve installed, it offers Reload and continue. That picks up exactly where you left off; the site address you typed is kept, so you never start over.

Install it: Chrome

1. In a new tab, go to relai.team/chrome. That forwards you to relai’s Chrome Web Store listing.
2. Click Add to Chrome, then Add extension when Chrome asks you to confirm.
3. Go back to the relai setup tab. It moves on by itself once it sees the extension.

If you do not see a relai icon in your toolbar afterwards, click the puzzle-piece Extensions button at the top right of Chrome, find relai in the list, and click the pin icon next to it. You will use that icon constantly, so it is worth pinning now.

Install it: Firefox

1. In a new tab, go to relai.team/firefox. That forwards you to relai’s listing on Firefox Add-ons.
2. Click Add to Firefox, then Add when Firefox asks you to confirm.
3. Recent versions of Firefox also show a short data-collection notice for the extension. relai declares that it handles website content, your account email, and the addresses of pages you pin, the same things described in How relai works. Accept it to continue.
4. Go back to the relai setup tab. It moves on by itself once it sees the extension.

Install it: Safari

relai for Safari isn’t available yet: it’s waiting on Apple’s review. If you’re on a Mac, use Chrome or Firefox for now; the setup wizard says the same and offers you both. Your account, workspace and sites are the same whichever browser you use, so nothing is lost by switching later.

Once Safari is available, it takes two extra steps that Chrome and Firefox don’t:

1. Install relai from the Mac App Store via relai.team/safari, then open Safari and go to Settings → Extensions and switch relai on.
2. In that same panel, give relai permission for relai.team. Safari asks per site, and relai cannot finish connecting to your account without it.

Connect it to your account

Once the extension is installed, the wizard shows Connect relai to your account with a single Connect button. Click it.

relai opens an approval screen titled Connect relai to this browser, with the note The relai extension on this browser will act as you. It shows the account you are signed in as, the workspaces this browser will cover, and exactly what it will be able to do. Click Approve and connect.

In Chrome this opens as a small window. In Firefox and Safari it opens as an ordinary tab, which closes itself once you approve.

Back in the setup tab both checks turn green, Extension installed and Connected as your email address, and the wizard moves itself on to the last step.

Step 5: Enable relai on your site

The last wizard screen is titled Enable relai on followed by your site address. This is a browser permission: you are telling your browser that relai is allowed to run on that particular site. Your browser will only accept that instruction from the extension’s own menu, which is why it takes three clicks rather than one.

The screen lists them:

1. Click the Open button for your site. It opens in a new tab.
2. Click the relai icon in your browser toolbar.
3. Click Enable relai on this site and approve the permission prompt your browser shows.

While it waits, the setup tab shows Waiting for permission…. The moment the permission is granted it changes to Enabled. Adding your site…, then Adding…, and finally All set.

You go back to All pins if you started from the short list there, or to the Sites page.

Step 6: Drop your first pin

Go to your site. The tab you opened in the last step is fine. Reload it once if you opened it before enabling relai.

In one corner of the page there is now a small round relai button with a target symbol on it. Hovering it shows a tip ending click to pin · drag to move. If it is in your way, drag it somewhere else.

1. Click the round button. (Or press Alt+Shift+P, or Option+Shift+P on a Mac.) A small toolbar appears in place of the circle.
2. Choose what to capture. The toolbar offers three modes: Element, Region and Full page. Element is selected for you and is the one to use: it is what makes a pin precise.
3. Move your mouse over the page. Things light up as you pass over them. A banner tells you to click one to pick it.
4. Click the thing you want to report. The button that does the wrong thing, the text that is wrong, the image that will not load.

If the page is animating and you need it to hold still, click the pause button in the toolbar first. It freezes videos and animations so you can pin the moment. To back out at any point, press Esc or click Exit (Esc).

A panel headed New pin opens with your capture in it. Fill it in:

• The first time only, relai asks who’s dropping pins? and wants Your name and Your email. It remembers them afterwards.
• What needs to change? Describe the problem in your own words. Plain English is fine; you are not writing a bug report. If you would like relai to tidy your note into a clearer one, click AI Assist. It may ask you a clarifying question, and you can always edit or ignore what it writes.
• Type: UI for how something looks, Logic for something behaving wrongly, Data for wrong information. (Your workspace may have its own set instead.)
• Priority: Urgent, High, Medium or Low. Medium unless you change it.
• Due date, Assignee and Labels are all optional. Skip them for your first pin.
• If your workspace has network capture switched on and there was something to record, you will also see a ticked box offering to attach a number of network requests, redacted, and possibly a line about recent actions (no typed values). It shows you a preview of exactly what would be attached. Leave it ticked unless you have a reason not to: it is often the part that makes a bug fixable. Untick it and none of it is sent.

Click Save pin.

Step 7: Where your pin goes

Your pin lands in three places at once.

On the page itself. A coloured marker stays where you pinned. Anyone else on your team with relai enabled on that site sees it there too. Click a marker to read the note, add a comment, mention a teammate with @name, or click Open in dashboard →. The ⋯ button in the toolbar controls which markers are shown (Open, In progress, Resolved) and how visible they are.

In the dashboard. Go to staging.relai.team, or click Pins in the left sidebar. Every pin in the workspace is here. You can view them as a Grid or as a Board grouped into columns. Click any pin to open it in full: the screenshot, the exact element, and everything relai captured alongside it.

As a notification. The bell in the top bar collects pin activity: new pins, comments, mentions, status changes. You can adjust what you get under Settings → Preferences.

That is a complete pin. Everything from here on is about getting other people into the same workspace.

Inviting your teammates

Inviting is done by a workspace’s Owners and Admins. In the left sidebar, click Settings, then People. (If you do not see People, you are not an Owner or Admin of this workspace.) The People page opens, with everyone already in the workspace.

1. Click Invite people, at the top right. A card opens under the title.
2. Under Email, type your teammate’s email address.
3. Under What can they do?, choose Admin, Member or Comment only. In short: an Admin can manage the workspace and its people, a Member can capture and triage pins, and Comment only can read pins and comment on them. The full breakdown is in How relai works.
4. Click Send invite. Their address appears in the Pending invites card, under the list of people, with their access and Resend and Revoke buttons next to it.

What each teammate has to do themselves. Registering the site is a one-off for the whole workspace: nobody repeats Step 3. But the extension is per person and the site permission is per browser, so each new teammate must:

1. Install the relai extension (Step 4).
2. Connect it to their own account. The relai icon shows Connect to relai until they do.
3. Open your site, click the relai icon, and click Enable relai on this site.

That last step is quick for them, because the site is already registered: they get the Enable button straight away rather than being sent to register anything.

If something doesn’t work

There’s no relai button on my site

Click the relai icon in your toolbar and read what the popup says. It names the problem directly:

• Connect to relai: the extension is installed but not attached to your account. Click the button and approve.
• Register this site on relai, with the note This domain isn’t registered in relai yet: relai does not know this address. Often it is a near miss: the site is registered as www.acme.com but you are on acme.com, or as https:// but you are on http://. Check the exact address on the Sites page in the dashboard.
• Enable relai on this site: the site is registered, but this browser has not been given permission yet. Click it.
• A green dot and Enabled on your site: relai is on. Reload the page; the round button appears on load.

A site on the dashboard is showing a warning

On the Sites page each site has a status line that names the specific reason, with a button that fixes that reason:

• relai extension isn’t installed in this browser: nothing to talk to here. Install extension takes you to the right store.
• Extension is installed but not signed in: it is here but holds no account. Connect starts the sign-in.
• Extension is signed in as …: a different account than the one you are using on the web. Connect rebinds it to this one.
• relai isn’t enabled on …: the site is registered, but this browser has no permission for it. Reconnect repairs it in place whenever the browser permission is still there; the page also tries this on its own, so a site often goes green without you clicking anything. If the permission is genuinely gone, open the site, click the relai icon, and click Enable relai on this site.
• A different relai build answered: you have more than one relai extension installed (usually a development build next to the store one). They do not share permissions, so this tells you nothing about the site itself: the store extension may be working there perfectly. Remove the extra build.
• Can’t tell, the extension isn’t answering: it responded to a ping and then went quiet, so we will not guess. Reload the page and try again.

All of these describe the browser you are looking at right now. A colleague on another machine can be perfectly fine while you see a warning, and vice versa.

A banner says the extension is signed in as a different account

The message reads Extension signed in as a different account. It happens when you sign in to relai as one person but the extension in that browser was connected as another: a shared machine, or a personal and a work account. Click Reconnect extension on the banner. If that does not take, open the relai icon and use the Reconnect as… button there.

I saved a pin but I can’t find it in the dashboard

• Check which workspace you are looking at. If you belong to more than one, the switcher at the top of the left sidebar changes what the dashboard shows.
• Check your filters on the Pins page. A site or status filter left on from earlier will hide it.

The keyboard shortcut does nothing

Alt+Shift+P only works on a page where relai is enabled, and another extension may have claimed the same combination. Click the round relai button instead; it does exactly the same thing.

The popup says it couldn’t reach relai

You will see Couldn’t reach relai. Check your connection and try again. and a Try again button. It is usually a dropped connection or a browser that put the extension to sleep. Click Try again; if it persists, reload the page and reopen the popup.

My pin has no screenshot

The pin still saved, and everything else about it (the element, the page, the console errors) is intact. Some sites block the screenshot step. It is worth reporting to whoever looks after that site, but it does not mean the pin failed.

relai keeps pointing at the wrong thing

If pins on a particular site drift onto the wrong element after a redesign, that site’s developers can fix it permanently in about a minute per element. Send them Make relai pin the same spot every time.