Connect to a server

In Remote mode, the Mac app is a client for a harnessd server. You add the server once with its URL and how to check its certificate, sign in with the account an admin created for you, and its projects appear in the sidebar under Servers.

Before you begin#

Get these from the server's admin:

• the URL: a domain such as https://fabrik.example.com for a server behind a load balancer, or https://127.0.0.1:9443 through an SSH tunnel;
• for a tunnel, the certificate SHA-256, from harnessd fingerprint --config /etc/harness/harnessd.yaml, and SSH access to the server;
• your username and initial password, and whether you need an authenticator code.

For a tunnel, open it before you add the server, and keep it running while you use it:

ssh -N -i ~/.ssh/harness-server.pem -L 9443:127.0.0.1:8443 ubuntu@203.0.113.10

macOS rejects a self-signed certificate on any address other than loopback, even a pinned one, so connecting to the server's own IP address fails. See Connect the app to a server.

Add the server#

1. Open Add Server

   In the sidebar's Servers section, click Add Server.

2. Fill in the connection
   • Name: what the sidebar shows, for example Team server.
   • URL: the server's domain, for example https://fabrik.example.com, or https://127.0.0.1:9443 through a tunnel.
   • Certificate: Public certificate for the domain for a server with a domain URL; there's nothing more to enter. Pinned fingerprint for a tunnel, then paste the Certificate SHA-256 (AB:CD:…).
   • Username.

   Press Add.

3. Sign in

   Select the server in the sidebar. Enter your password and press Sign In. If your account has an authenticator, the panel says Now enter the code from your authenticator; type the 6-digit code and sign in again.

The session token is kept in your Keychain; your password isn't stored. While the server keeps the session alive, restarting the app signs you back in without a password. The token is sealed to the server entry it was issued for (scheme, host, port, certificate mode, pin and username): if that entry changes, for example its address or pin is edited in servers.json, the app signs you out instead of sending the token elsewhere. After upgrading to a version with sealed tokens, everyone signs in once more.

With Public certificate for the domain, the app accepts only certificates that chain to the root authorities macOS ships with. Certificates or roots added to this Mac and marked as trusted, by you or an administrator (a debugging proxy's CA, for example), are refused for SI Fabrik servers.

What you see#

Once signed in:

• The server's projects appear under it in the sidebar, with the same rows as local projects and a badge for running agents. See Server projects.
• Selecting the server opens Server Settings, with the same tabs as the app's Settings window, and your role. See Server Settings.
• The Sandboxes screen lists the server below this Mac. See Server sandboxes.
• Admins get Add Project under the server, and Move to Server on local projects. See Projects on a server.

Sign out or remove a server#

Right-click the server in the sidebar:

• Sign Out ends the session on the server and forgets the token.
• Remove Server removes it from the app.

Server Settings → General → Account also has Sign Out.

Your session also ends when it's idle for longer than the server allows (session.idle_minutes, default 60), after session.absolute_hours (default 12), when the server restarts, when your password changes, or when your account is disabled. The app then asks you to sign in again.

If you can't connect#

See also#

• Connect the app to a server
• Server projects
• Roles in the app
• TLS and certificate pinning