Getting started

How DartRelay works

This page explains, in plain language, the pieces that make up a DartRelay installation and what happens between a person clicking an application and that application appearing in their browser. Knowing this makes the rest of the help centre, and most troubleshooting, much easier to follow.

The big picture

A DartRelay installation has five parts. Only one of them, the DartRelay server, is something you install. The others are either websites it serves, Windows machines you already have, or a database it keeps its settings in.

  Person's browser                DartRelay server                     Hosts
  (any device)                    (one Windows or Linux machine)       (your Windows machines)

  +-------------+   HTTPS and     +------------------------------+     RDP     +------------------+
  |  Portal     | <-------------> |  Portal and console websites | <---------> |  Windows desktop |
  |  (a tab per |   secure        |  Access decisions, seats     |   (3389)    |  or Windows      |
  |  session)   |   WebSocket     |  Session relay               |             |  Server with the |
  +-------------+                 +------------------------------+             |  Session Host    |
                                        |              |                       |  role            |
  Administrator's browser               |              |                       +------------------+
  +-------------+   HTTPS               v              v
  |  Console    | <-------------> Database        Directory (optional)
  +-------------+                 SQLite file or  Active Directory,
                                  SQL Server,     Microsoft Entra ID,
                                  MySQL,          OpenID Connect
                                  PostgreSQL

Read it from left to right: a person's browser only ever talks to the DartRelay server. The DartRelay server talks to the hosts. The hosts never talk to the browser directly, and the browser never needs a route to them.

The pieces, one at a time

The portal

The portal is the website your users sign in to. It is served by the DartRelay server at the address you give it, under /portal (for example https://apps.example.com/portal). After signing in, a person sees My Resources: the applications, desktops and web applications they have been given. When they open one, it appears as a tab along the top of the same page. The portal carries your branding and can look different on each address people browse to. See Themes and Tenancy & Branding.

The console

The console is the administrator's website, also served by the DartRelay server, under /admin. Everything you configure, from hosts and resources to users, themes, security and licensing, is done here. Administrators can be given different permissions for different areas of the console. See Administrator roles and permissions.

The DartRelay server

This is the machine you install DartRelay on, and the only place DartRelay software runs. It runs as Windows services (or the equivalent on Linux) that start automatically. It does three jobs:

Serves the portal and the console over the web port you chose during installation.
Decides who may open what. Each time someone opens a resource, the server checks that they are entitled to it, that the resource is in a category they may see, and that the licence has a Relay Seat available for their device.
Relays the session. The server makes a Remote Desktop (RDP) connection to the host on the user's behalf, turns the Windows screen into a picture stream the browser can draw, and carries the user's keyboard, mouse, clipboard, file transfers and printing back the other way. Between the browser and the server this travels over HTTPS and a secure WebSocket, the same kind of connection modern web applications use for live updates.

Because the server makes the RDP connection itself, the Windows password used to log on to a host is handled on the server and never reaches the browser.

Hosts

A host is a Windows machine you publish applications or desktops from. It can be a Windows desktop edition or a Windows Server. To let more than one or two people work on a Windows Server at the same time, it needs the Remote Desktop Session Host role, which DartRelay can detect and install for you.

DartRelay is agentless: nothing is installed on a host. To check a host's readiness, list the programs installed on it and register the applications you publish, DartRelay connects with a management account (a local administrator account you give it on the host's page) over standard Windows file sharing and remote registry. To deliver sessions it uses RDP, exactly as the Remote Desktop client built into Windows does. See Adding and preparing hosts.

The database

Everything you configure is stored in one database: hosts, resources, users and groups, themes, settings, the audit log and the licence state. You choose the database when you first open the console:

SQLite: a single file in DartRelay's data folder. Nothing to set up, ideal for one server.
SQL Server, MySQL or PostgreSQL: a database server you already run. Needed when several DartRelay servers share one database in a pool.

See Databases and migration.

The data folder

Alongside the database, each DartRelay server keeps a small data folder: the App_Data folder inside the installation folder. It holds the SQLite database (if you use SQLite), the server configuration file dartrelay.config.json, logs, and the keys used to encrypt stored passwords. The installer locks it down so only the system and administrators can read it. See Server configuration file.

Directories and identity providers (optional)

People can sign in with accounts you create in DartRelay itself. You can also let them sign in with Windows local accounts on the DartRelay server, with Active Directory accounts, and, from version 2.1, with Microsoft Entra ID or another OpenID Connect provider. See Active Directory and multiple domains, Microsoft Entra ID sign-in and OpenID Connect sign-in.

What happens when someone opens an application

Here is the journey of one click, from start to finish.

The person signs in. They browse to the portal address and sign in. DartRelay checks their password against the right place (its own accounts, Windows or Active Directory), applies any second factor or Agreement, and checks that this address admits them.
The portal shows My Resources. DartRelay works out which resources this person is entitled to, directly or through their groups, and hides anything in a folder they may not see.
They click an application. The browser asks the DartRelay server to launch it. The server checks the entitlement again (the portal is never trusted on its own), checks the licence, and takes a Relay Seat for this device if it does not already hold one.
The server connects to the host. It opens an RDP connection to the host the application is published from, logging on either with the person's own Windows credentials (Pass-Through) or with an account stored on the resource (Fixed Credentials). From version 2.1 it can instead log on with a short-lived certificate (Relay Pass).
Windows starts the program. For a published application, Windows starts just that program and shows only its window. For a desktop, it shows the whole desktop.
The session appears in a tab. The server streams the picture to the browser over the secure WebSocket, and the browser draws it in a new tab in the portal. Keyboard and mouse input flows back the same way.
More applications join the same session. If the person opens a second application from the same host, it normally opens inside the same Windows session, as another tab, so it starts quickly and shares the same files and clipboard.
The session ends. When the person closes the tab, signs out, or is idle for longer than you allow, DartRelay ends the session. When the device's last session ends, its Relay Seat is released for someone else.

Example: a company with two offices

A firm has a head office and a branch. Its accounting program runs on one Windows Server at head office, and staff in both offices, and at home, need it.

They install DartRelay on a second server at head office, choose SQLite, and activate their licence.
They add the accounting server as a host. DartRelay reports that the Remote Desktop Session Host role is missing and installs it, then the server is restarted once.
They publish the accounting program, give access to the Active Directory group Accounts, and publish the portal through their firewall at https://apps.firm.example.
A member of staff at the branch, or at home, opens a browser, signs in with their usual Windows username and password, and clicks the accounting icon. It opens in a tab within seconds. Their laptop needs no software, and no VPN.

Only one port on the DartRelay server is reachable from outside. The accounting server stays on the internal network and is reached only by DartRelay.

One server, or several

Most installations are one DartRelay server. If you need more capacity, or want to be able to take a server out for maintenance without stopping the service, you can run several DartRelay servers that share one database behind a load balancer. They share every setting, so you configure the pool once. Two things to understand:

A session stays on the server it started on. The load balancer must keep each person on the same server, and if that server stops, the sessions on it end. A pool gives capacity, not failover.
Every server in a pool must run the same version. Upgrade them together. See Upgrading DartRelay.

See Running several servers (pools) and Load balancer and ADC integration.

What travels where

Between	What	How
Browser and DartRelay server	Portal and console pages, the session picture, keyboard and mouse, file transfers	HTTPS (or HTTP while you set up) and a secure WebSocket on the web port you chose
DartRelay server and hosts	The Windows session	RDP, normally TCP port 3389
DartRelay server and hosts	Readiness checks, the list of installed programs, publishing applications, installing the Session Host role	Windows file sharing (SMB, TCP port 445), remote registry and Task Scheduler, using the host's management account
DartRelay server and database	Settings, users, resources, audit	Local file (SQLite) or the database server's own port
DartRelay server and directory	Sign-in checks, users and groups	Windows sign-in and LDAP to your domain controllers

The full list of ports is on System requirements.

If something goes wrong

Knowing the path a session takes tells you where to look:

The portal will not load at all: the browser cannot reach the DartRelay server. Check the address, the port and any firewall in between. See Endpoints and certificates.
The portal loads but nothing launches, especially behind a load balancer or proxy: the secure WebSocket is being blocked. See Load balancer and ADC integration.
Launching is refused with a licence message: there is no valid licence, or every Relay Seat is in use. See Licensing and Relay Seats.
The session starts and is refused by the host: the problem is between the DartRelay server and the host: the account, its right to sign in through Remote Desktop, or the host's Remote Desktop licensing. See Troubleshooting.