Support

01Getting started on your Mac

1. Download Sovernity Ursa from the Sovernity Ursa page (/ursa/) and open the DMG. Drag Ursa to your Applications folder.
2. Open it. macOS asks you to confirm the first time.
3. The model download. Ursa needs a one-time download of about 7 GB: Gemma 4 12B and a small search model. If it's interrupted, choose Resume download: what has downloaded so far is kept. Ursa checks every file before using it. Already have the files? Choose I already have the files…. After this download, Ursa never goes online.
4. The Introduction (optional). While the model downloads, Ursa offers to get to know you with a few questions. It helps Ursa understand you from day one. You can skip it with Maybe later and do it any time from What I know about you, or Settings › Data.

Need: a Mac with Apple silicon and 16 GB of memory or more, macOS 15 or later, and about 9.1 GB of free space.

02Connecting your iPhone

Do this once, at home, with both devices on the same Wi-Fi.

1. On your Mac, open Ursa and go to Settings › Phone › Pair an iPhone. Your Mac shows a code.
2. On your iPhone, open Ursa and tap Scan the code, then point the camera at the code on your Mac. Ursa uses the camera only to read this code.
   • Can't scan? On your Mac, choose Copy code, then on your iPhone tap Paste the code instead.
3. iOS asks to find devices on your network. Allow it, so your iPhone can reach your Mac on your Wi-Fi.
4. Check the three words. Your iPhone and your Mac each show three words. If they're the same, confirm on your Mac with Touch ID or your password. If they don't match, choose Cancel: nothing is paired.

Codes last five minutes. If yours expired, make a new one on your Mac.

The connection is encrypted, and no server is involved. Your iPhone keeps only an encrypted draft of a message you haven't sent yet; everything else stays on your Mac.

Tip: on your Mac, Stay available while plugged in (Settings › Phone) keeps Ursa reachable while it charges.

If you said no to Local Network access: Ursa shows "Ursa can't see your network". Open your iPhone's Settings › Privacy & Security › Local Network, turn on Ursa, then try again.

If the camera is off for Ursa: paste the code instead, or allow the camera for Ursa in your iPhone's Settings.

03If your iPhone can't reach your Mac

Your iPhone tells you which of these it is:

• "[Your Mac] is out of reach." Make sure your Mac is awake, Ursa is open on it, and your iPhone is on the same Wi-Fi, or set up Tailscale for away from home (section 4).
• "Your Mac is busy right now." For example while Ursa is being set up. Your chats show again when it's ready.
• "Ursa can't see your network." Allow Ursa under Settings › Privacy & Security › Local Network.
• "Your Mac no longer recognises this iPhone." The iPhone was removed on your Mac. Tap Pair this iPhone again.
• "Update Ursa on your Mac" or "Update Ursa on your iPhone". One of them is older than the other; update it (section 5).

While your Mac is out of reach, what you've typed is kept as an encrypted draft on your iPhone.

To remove a paired iPhone: on your Mac, Settings › Phone › Paired iPhones › Remove…; or on the iPhone, Settings › Your Mac › Unpair this iPhone. Unpairing removes the pairing and any unsent message from that iPhone.

04Away from home with Tailscale

At home, your iPhone finds your Mac over your Wi-Fi. Away from home, it needs Tailscale: a free, private network between the devices you own.

1. Install Tailscale on your Mac and your iPhone, from the App Store. On your Mac, Ursa's guide is at Settings › Phone › Use Ursa away from home › Show steps…; on your iPhone, Settings › Your Mac › Use Ursa away from home.
2. Sign in on both with the same Tailscale account.
3. That's it. Your iPhone learns the way back the next time it connects at home.

Tailscale can see that your devices exist, never what they say.

Your chats and what Ursa knows stay on your Mac. Running your own Headscale server instead? That works too: Ursa only looks for the address your tailnet gives your Mac.

05Updating

• Mac: download the new version from the Sovernity Ursa page and replace the app in your Applications folder. Your data stays where it is, and the model isn't downloaded again unless the release notes say so. Ursa never updates itself.
• iPhone: updates come from the App Store.
• Keep both up to date. If one is too far behind, your iPhone says which one to update.

06Backup, restore and export

All in Settings › Data on your Mac.

• Back up… saves everything Ursa has, your chats and what it knows about you, to one file locked with a password you choose (at least 8 characters). Save it wherever you like. Ursa never uploads it. Keep the password safe: without it, nobody can open the backup, including us.
• Restore… replaces everything on this Mac with a backup. Your current data is set aside on this Mac, not deleted, and Restore it… brings it back if you change your mind.
• Export… saves a readable copy of your chats and profile for your own records. The export is not encrypted: anyone who can open the file can read your chats and what Ursa has learned about you.

Moving to a new Mac: back up on the old Mac, install Ursa on the new one, then restore. Pair your iPhone again from the new Mac. Restore works before or after the model download: Settings › Data › Restore… is there as soon as you've confirmed you're 18 or older.

07Deleting your data

• One fact: in What I know about you, delete or correct it.
• One chat: delete it from your chats. Deleting a chat deletes the chat and the facts learned only from it. Your broader profile is managed in What I know about you.
• Talk without Ursa learning: turn off learning for that chat. It shows "Not learning from this chat".
• Everything: Settings › Data › Delete everything…. This deletes every chat and everything Ursa knows about you, and unpairs your iPhones. The model files stay on your Mac. This can't be undone.

08Uninstalling

Mac

1. In Ursa, Settings › Data › Delete everything… (optional, but it removes your data right away).
2. Quit Ursa and move it from your Applications folder to the Trash. Then move the folder ~/Library/Containers/com.sovernity.ursa.app to the Trash. It holds the model files and any data Ursa kept. In Finder, Go › Go to Folder… takes you there.
3. Ursa's keys stay in your Mac's Keychain after you uninstall. Without the folder above, they can't unlock anything.

iPhone

• Unpair first if you can (Settings › Your Mac › Unpair this iPhone), then delete the app like any other. If you delete the app without unpairing, the pairing can stay in your iPhone's Keychain, and reinstalling Ursa may find it again. Unpairing first removes it.

Your answer to the 18+ question is kept until you remove that folder on your Mac, or delete the app on your iPhone; a reinstall then asks again.

Backups and exports you saved are your own files; delete them where you saved them.

09If your Mac isn't supported

Ursa runs its AI model on your Mac, and that takes a Mac with Apple silicon and 16 GB of memory or more.

• Intel Macs can't run Ursa. It's built for Apple silicon only.
• Macs with 8 GB of memory: Ursa checks before downloading anything and tells you "Ursa needs a Mac with Apple silicon and at least 16 GB of memory. This Mac has 8 GB of memory." Nothing is downloaded.
• macOS 14 or earlier: Ursa needs macOS 15 or later.

Ursa for iPhone needs a Mac running Ursa; it doesn't run the AI on the iPhone.

10Help in a crisis

• On iPhone: Settings › Help in a crisis. It's built into the iPhone app and works even when your Mac is out of reach. Before your iPhone is paired with a Mac, it's on the welcome and pairing screens.
• On Mac: Help › Help in a crisis, or Settings › About › Safety. It's built into the Mac app and works without a connection, with the numbers set large so you can dial them from any phone.
• Call or text 988, the 988 Suicide & Crisis Lifeline, or call 911 if you're in immediate danger. Outside the US, call your local emergency number.
• Ursa is an AI, not a person or a therapist.
• It isn't a crisis service. It can miss things, and it can't contact anyone for you.
• How Ursa responds to signs of a crisis: the crisis protocol (/ursa/crisis-protocol/).

11Reporting a problem

Email support@sovernity.com. It helps to include:

• The Ursa version (Mac: Settings › About; iPhone: Settings, at the bottom).
• Your Mac model, its memory, and your macOS version; your iOS version if it's about the iPhone.
• What you did, what you expected, and what happened.

Ursa doesn't send logs or crash reports to us, so there's nothing on our side to look up.

A reply that seemed unsafe, or crisis help that showed when it shouldn't have (or didn't when it should): please tell us. Describe it in your own words; you don't need to paste the conversation, and please leave out anything you'd rather keep to yourself. If you're in crisis right now, call or text 988, or call 911, first.