Skip to content

Connect your Mac to official Dev and QA

Status: Current | Last reviewed: 2026-09-21

This guide is only for your laptop. Your city host must already have a working TrueServe relay. The relay lets your browser reach official Dev and QA, including voice traffic, while you keep your normal core VPC VPN connected.

You will use one WireGuard connection for both environments. Dev and QA remain separate websites, with their usual sign-in pages.

For startup after reboot, route updates and a 30-minute connection check, use Automatic laptop access maintenance with a fresh bundle after your city owner enables discovery. The steps below remain the manual connection option.

1. Get your personal connection bundle

Ask your city owner for a Mac laptop bundle for your device. Tell them your city and a device name, such as eric-mac. You should receive a private ZIP containing:

  • both/TrueServe.conf — your connection profile for Dev and QA together.
  • dev/TrueServe.conf and qa/TrueServe.conf — optional single-environment profiles.
  • mac.sh — the connection and DNS helper.
  • MAC-SETUP.md — this guide.

The profile contains your private key. Keep it in your own user folder; do not post it in chat, commit it to Git, or share it with another developer. A second laptop needs its own bundle. The bundle is specific to your city relay.

Extract the ZIP into a folder such as ~/TrueServeAccess/eric-mac. Keep the files together. The helper reads the profile and its accompanying settings.

2. Connect your normal core VPC VPN

Connect the same corporate/core VPN you normally use to reach your city. Leave it connected throughout this procedure.

What this does: the core VPN provides the route from your Mac to the city's private address. WireGuard runs over that existing connection. It does not replace your core VPN.

3. Install WireGuard

Choose one option below. Do not activate the same profile in both tools.

Option A: Homebrew command-line tools

If you use Homebrew, open Terminal and run:

brew install wireguard-tools

What this does: installs wg and wg-quick, the tools the helper uses to create and manage the tunnel. Homebrew does not install the Mac GUI app.

If Homebrew is not available on your managed Mac, use Option B or your approved software installation process.

Option B: WireGuard app

Install WireGuard from the Mac App Store using your approved installation process. Launch the app.

What this does: gives you an Import/Activate interface for the connection. You will still run the DNS helper in Terminal so only TrueServe names use the city's resolver.

4. Open Terminal in your extracted bundle folder

For the example folder above:

cd ~/TrueServeAccess/eric-mac
ls

Check that mac.sh and the both folder appear. Substitute your actual folder name in the cd command.

What this does: puts Terminal alongside the files used by the next commands. All remaining commands in this guide run from this folder.

5. Activate Dev and QA

With Homebrew

sudo bash mac.sh up both

Enter your Mac password if prompted. Terminal does not display password characters while you type.

What this does: starts the tunnel, checks its routes, asks the city resolver for a TrueServe address, and then enables DNS for the listed TrueServe names. It adds selected destination routes rather than changing your default route.

With the WireGuard app

  1. Choose Import tunnel(s) from file.
  2. Select both/TrueServe.conf from your extracted bundle.
  3. Select the imported TrueServe tunnel and click Activate.
  4. Return to Terminal and run:

bash sudo bash mac.sh dns-on both

What this does: the app starts the tunnel; dns-on makes your Mac resolve the selected Dev/QA names through it. Importing the profile alone does not install these scoped DNS settings.

6. Verify the connection

sudo bash mac.sh status

What this does: checks the city endpoint route, the tunnel's DNS response, and the available WireGuard status. The city endpoint must still use your core VPN, while TrueServe destinations use the new tunnel.

With the Homebrew tools, look for a recent latest handshake and an answer for Studio DNS. A handshake confirms the two WireGuard peers can communicate; the browser and call checks below verify the application path.

7. Open the normal websites

Use these addresses directly in your browser:

Environment Studio Grafana ArgoCD
Dev https://studio.dev.trueserve.deloitte.com/ https://grafana.kms.dev.trueserve.deloitte.com/ https://argocd.kms.dev.trueserve.deloitte.com/
QA https://studio.qa.trueserve.deloitte.com/ https://grafana.truserve-qa-wus.qa.orchestrator.trueserve.deloitte.com/ https://argocd.truserve-qa-wus.qa.orchestrator.trueserve.deloitte.com/

Sign in normally and complete MFA. Allow microphone access when prompted. Try a voice call in each environment and confirm you can both speak and hear the reply. You can keep Dev and QA open in separate tabs.

What this does: verifies sign-in, signaling and real audio, which a green WireGuard status alone cannot prove. ArgoCD browser SSO can work even when its separately configured CLI SSO does not.

8. Disconnect when finished

With Homebrew

sudo bash mac.sh down

With the app

First run:

sudo bash mac.sh dns-off

Then click Deactivate in WireGuard.

What this does: removes TrueServe's temporary DNS settings and, for the CLI, stops its tunnel. Your normal core VPN can stay connected. Disable the DNS settings before turning off the app tunnel so your Mac does not keep sending TrueServe lookups to an unavailable connection.

Reconnect, switch or replace your profile

  • Reconnect: connect the core VPN, then repeat step 5. After a reboot or interrupted connection, run down first for the CLI if the helper reports an existing saved profile.
  • Dev only or QA only: disconnect first, then use up dev or up qa. App users disable DNS and deactivate/delete the old imported profile, import the new folder's TrueServe.conf, activate it, and run dns-on dev or dns-on qa.
  • New city or refreshed bundle: disconnect first, replace the entire bundle, and reconnect. App users must also replace the imported profile. Do not run two city tunnels simultaneously; they route overlapping websites.

both is the normal choice. You do not need to switch profiles just to move between Dev and QA tabs.

If something fails

  1. Confirm the core VPN is connected.
  2. Run sudo bash mac.sh status and save its output. Do not share the .conf file or private key.
  3. If activation failed, run sudo bash mac.sh down before retrying.
  4. If a browser cannot resolve a name but tunnel DNS works, check whether your managed browser's Secure DNS setting bypasses the system resolver. Ask your desktop support team to use system DNS for these names.
  5. If File exists or duplicate utun interfaces appear, deactivate any old TrueServe app/CLI connection and send the status output to your city owner. Do not disable your core VPN interface.
  6. If Studio loads but audio fails, check microphone permission and report the environment, time and whether one or both audio directions fail.

The old September 17 StudioTest proof-of-concept uses a separate migration script. Do not apply that old profile's hardcoded address repair to these new city bundles.

Legacy StudioTest: Dev works but QA times out after reconnect

On September 21, QA DNS published 52.40.176.56 and 54.185.47.193, while the older StudioTest profile allowed only the earlier QA addresses. A recent WireGuard handshake therefore did not prove that QA requests used the tunnel. The legacy relay was updated to admit the new addresses and to make its scoped DNS snapshot readable by its DNS process.

For that original profile only, replace the Mac's old upgrade-studio-test-mac.sh with the repository's v4 copy. Keep the core VPN and working StudioTest tunnel connected, then run from StudioTest-mac:

sudo bash upgrade-studio-test-mac.sh ./StudioTest.conf

This checks the live tunnel identity, preserves existing routes, adds the reviewed QA destinations to both the active tunnel and saved profile, and verifies QA HTTPS before enabling scoped DNS. Its private backup stays beside the profile. If it reports an unrelated route conflict, stop and provide that output; do not overwrite your core VPN routes.

These are address snapshots, not automatic discovery of future load-balancer changes. When DNS addresses change again, refresh and verify both relay and client routes before distributing an updated profile.