Log in

Installing the Agent Workspace

Get the Headways desktop app installed, signed in, and connected to your org.

The Agent Workspace is a desktop app for macOS that powers the Inbox, Outbox, and Skills surfaces. This guide gets you from zero to your first signed-in workspace in under five minutes.

Prerequisites

  • macOS 13 or later (Apple Silicon or Intel)
  • A Headways workspace your org admin has invited you to
  • The email address tied to your invite

Step 1: Download

Download the latest Mac installer:

https://storage.googleapis.com/headways-releases/desktop/latest/Headways-latest.dmg

This URL is permanent — it always serves the latest signed build. No need to track version numbers.

Step 2: Install

  1. Open the downloaded .dmg.
  2. Drag Headways.app into your /Applications folder.
  3. Eject the .dmg.
  4. Launch Headways from Applications or Spotlight.

On first launch, macOS may show a Gatekeeper prompt. Right-click the app → Open → confirm. After the first launch you'll open it normally.

Step 3: Sign In

The app opens to a sign-in screen.

  1. Click Sign in with your work email.
  2. Enter the address that received the invite.
  3. Complete SSO if your org has it configured. Otherwise, follow the email magic link.
  4. Pick your workspace if you belong to more than one.

You'll land in your Inbox. It's empty on day one — that's expected. Inbox items arrive once Connectors are wired and Skills are running.

Step 4: Confirm Setup

A few quick checks before you start the next guide:

  • Inbox / Outbox / Skills tabs visible in the left rail — confirms the workspace is loaded.
  • Workspace name in the header matches your org — confirms the right scope.
  • Personal vs Shared toggle present — confirms you have both scopes.

If anything is missing, your invite may not have been provisioned fully. Ping your admin or contact support.

What's Next

The workspace is installed but inert until it's connected to your work. Two suggested next steps:

Connect Your First Data Source

Wire Gmail, Slack, CRM, Calendar, or Linear into the workspace.

Publish Your First Skill

Author a Skill via the CLI and make it available to your team.

Troubleshooting

SymptomFix
App won't open ("damaged or unidentified")Right-click → Open to bypass first-launch Gatekeeper
Sign-in stuck on SSO redirectAllow third-party cookies for your IdP, or sign in to your IdP separately first
Empty workspace dropdown after sign-inYour admin needs to add you to a workspace; verify the invited email matches
Updates not arrivingThe app checks on launch; quit and relaunch to force a check