Documentation for SpaceAtlas

1. Download SpaceAtlas and run the .pkg installer. Follow the on-screen steps to complete the installation.
2. Launch SpaceAtlas. The Set up SpaceAtlas window asks for two permissions, one step at a time: Accessibility, so SpaceAtlas can move your windows, and Input Monitoring, so it can hear your shortcut keys. Click Open System Settings and switch SpaceAtlas on. If it is not in the list, use Show SpaceAtlas in Finder and add it. After granting Input Monitoring you may need Quit & Reopen.
3. The tutorial starts with four short steps on your real screen: where your spaces live, your first jump, giving a space some apps, and bringing them back. After that you can use SpaceAtlas straight away, or continue with the optional chapters: Build your own map, Keep the map on screen, Set up your Space Map, The buttons on the Space Map, Where a new window goes, Make the keys yours, and Switch it off for a minute.
4. Optional: Settings → Advanced → Fine-tuning lists macOS settings SpaceAtlas works better with (Reduce Motion, Swipe between Full-Screen Apps, Displays have separate Spaces). None of them are required; each has an Open button that takes you to the right place in System Settings.

You can reopen the permission window at any time with Permissions in the menu bar panel, or with Help → Check Permissions….

SpaceAtlas asks for Accessibility and Input Monitoring on first launch and tells you when each one is granted.

SpaceAtlas runs from your menu bar. Click the icon to ask where the front window should go. Right-click it to open the SpaceAtlas panel:

• Pause / Resume — switch navigation off and on without quitting. The gear button opens Settings.
• Profiles — click a profile to switch to it. Each row has buttons to rename it, open it in the Map Editor, or delete it. + New Profile adds one.
• Launch Apps for Space / Save Apps to Space… — open the apps saved for the current space, or save what is open now.
• Keep Awake — stop your Mac from sleeping for a chosen number of hours, or forever.
• Tutorial, Permissions, Website, Restart, and Quit.

The menu bar panel is your quick-access hub for pausing, switching profiles, launching apps, and Keep Awake.

Making spaces

• Click an empty cell to make a one-cell space, then type its name right on the tile.
• Drag across empty cells to make a larger, rectangular space.
• Drag a space to move it, or drag its corner to resize it.
• Double-click a space, or right-click and choose Rename, to change its name.
• Right-click a space to change what it does.

A new space takes the lowest free space number. The On this map panel on the left counts your spaces and portals.

What a space does

Right-click a space and pick one of four behaviours under What this does:

• Holds apps · Space — an ordinary space for your windows.
• Teleports me somewhere · Wormhole — moving into it takes you straight to another place.
• Sends me to another profile · Gateway — moving into it takes you to a cell in another profile.
• Routes by the side I enter · Nexus — each side you enter from can lead somewhere different.

When you turn a space into a portal, SpaceAtlas asks where it should lead: Somewhere on this map, Into another profile, Wherever I was last, or Back the way I came. The last two follow your movement instead of pointing at a fixed cell, which makes them handy as a "back" button.

Wormholes and Gateways

A Wormhole is a one-way link inside the current profile. A Gateway works the same way but leads into another profile — useful for linking shared spaces between a Work and a Home setup. A wormhole cannot lead into another wormhole.

Nexus

A Nexus is a directional hub: entering from the left, right, top, or bottom can each lead somewhere different. Right-click a nexus and choose Edit the four sides… to open the Nexus Configuration window. Each side can pass straight through, act as a wormhole or gateway, or go to the last active or previous space. At least one side must be set.

Larger spaces

A space can cover several cells. Moving into it is a normal move; moving on through it carries you across its cells and out the far side, and moving back the way you came returns you to where you entered from. Right-click a multi-cell space to choose how it is entered:

• Remember where I was inside — the default; you come back to the cell you last used.
• Always enter at the edge — you always land on the cell next to where you came from.

Use Add Cells… and Remove Cells… in the same menu to reshape it cell by cell.

Quick Jumps

Quick Jumps take you to a space from anywhere with ⌘1 through ⌘9. Right-click a space and choose Jump key to give it a free number. The Quick Jumps panel on the right lists what is assigned in this profile.

Profiles

Profiles let you keep entirely different maps and switch between them — for example a "Work" profile and a "Home" profile. Pick a profile from the Profile menu at the top of the Map Editor to switch to it. Use Save New Profile to start a new one from the current map and Delete Profile to remove one you no longer need. You can also switch, rename, and delete profiles from the menu bar panel.

Click or drag empty cells to add a space. Drag a space to move it, or its corner to resize. Right-click to change what it does.

On screen

• Fading — the map is fully visible while your pointer is over it and for a few seconds after you switch space. Then it fades to the Opacity you set.
• Tools — buttons beside the map appear while your pointer is over it and fade out a few seconds after it leaves. Set Show Tools to Always to keep them. The pause button stays visible while SpaceAtlas is paused.
• Inbox — apps with windows that are on no space appear as icons next to the map. See Where Windows Go.
• Moving it — drag the map by its handle or hold and drag the grid, depending on the Dragging setting. Click the drag handle to switch between one position shared by every space and a separate position for each space.

Space Map settings

Settings → Space Map shows a live preview of your map as you change it.

• Enable Space Map and Collapse to drag handle when paused.
• Opacity, Size, and Dragging (Locked, Drag Handle, Grid Drag-and-Hold, or Both).
• Smooth local position transitions and Transition Speed — how the map glides when each space has its own position.
• Display — Full Grid, Images (with Image Size), Numbers, and Notes.
• Highlight — how the current space is marked: Border, Tint, Glow, or Border + Tint, with a colour and border and arrow sliders.
• Nexus Art — the artwork drawn on nexus cells.
• Inbox, Button Layout, and a checkbox for each tool button.
• Hide & Restore — optionally hide the map with a right-click, and bring it back with the Toggle Space Map shortcut, on the next space switch, or after a delay.

Navigation Mode

Also on the Space Map tab, Navigation Mode decides what happens when the next cell in your direction is empty:

• Carousel (Skip Unmapped) — wraps around the grid, skipping empty cells to the next space.
• Hit Wall (Stop at Unmapped) — stops at an empty cell, treating the gap like a wall.

The Space Map with app icons on each space, the inbox beside it, and the tool buttons on the right.

The Space Map tab previews your map in use and at its idle opacity.

The placement prompt

When a window appears that SpaceAtlas does not know yet, it asks once where it should live. It only decides on its own when there is a single possible answer: an app with one window that is set up on exactly one space. Open the prompt yourself at any time by clicking the menu bar icon, with the Where Does This Window Go button on the Space Map, or with ⌃⌥W.

• Quick pick — suggests up to three spaces. Choose one, choose Another Space (or type its number) for the full view, pick Show here, don't assign, or press Later.
• Full view — your map on the left and every open window on the right. Click a space to edit what it holds, hover one to preview it, or type its number. Tick a window to put it on that space; untick it to take it off. Nothing moves until you apply (↩ or the green button).
• Row menu — the ⋯ button on each window offers more: show it here without assigning, add it to or move it between spaces, pin it to every space, take it off all spaces, close the window, or quit the app.

The inbox

Windows that are on no space collect in the inbox next to the Space Map, one icon per app. Click an icon to Show here (show the window on this space without assigning it), Assign… it with the placement prompt, or Close it.

Apps that are closed

Closing a window or quitting an app keeps the app on its spaces. The space lists it as having no open window, and when you open it again it comes back where it belongs.

Each time SpaceAtlas starts, it looks at every open window once so the inbox and your spaces are up to date. You may see apps from other spaces appear briefly while it checks them.

Launching and saving apps

• Launch Apps for Space (⌥L, or the menu bar panel) opens the apps saved for the current space.
• Save Apps to Space… in the menu bar panel saves what is open now. This is also where you give a space an image.
• Settings → Advanced → Prompt to launch Space App on first visit offers to open a space's saved apps when you arrive and they are not running. Reset Launch Prompt Answers clears your earlier answers.

Following focus

With Follow Focused Saved Windows on (Settings → Advanced → Window Behavior), clicking or ⌘-Tabbing to a window saved on another space takes you to that space.

Fullscreen windows

A window in native macOS fullscreen takes over its space: the space gets two stops, the fullscreen window and the desktop, and the arrow keys move between them. Turn this off with Follow Native Fullscreen Windows in Settings → Advanced → Window Behavior.

Click a space on the map, tick the windows it should hold, and apply. Nothing moves until you do.

Actions are grouped on the left and can be searched by name, or by pressing a shortcut to find what uses it. Select an action to see what it does and its bindings on the right.

• Add keyboard shortcut / Add gesture — record a new binding. If another action already uses it, it moves to this one.
• Change / Remove — edit or delete an existing binding.
• Reset this action and Reset All to Defaults — go back to the original bindings.
• Disable Keyboard Shortcuts — turn off all shortcuts without losing your bindings.
• Gestures — sensitivity lives in Settings → Advanced → Trackpad & Mouse Gestures. Gesture support is experimental and may stop working after your Mac wakes from sleep; if it does, restart SpaceAtlas from the menu bar panel.

Defaults

• Navigate Space — ⌥ + arrow keys.
• Jump to Space 1–9 — ⌘1–⌘9, assigned per profile in the Map Editor.
• Jump to Last Space — ⌘0 toggles between your current and previous space.
• Previous / Next App in Space — ⌘⌥← and ⌘⌥→.
• Where Does This Window Go — ⌃⌥W opens the placement prompt.
• Launch Apps for Space — ⌥L.
• Reset Current Space — ⌃⌥R.
• Pause Navigation — ⌃⌥P.
• Atlas Quit — ⌥Q lets you pick and quit apps running on the current space.
• Open Activity Monitor — ⌥⇧A.

Save Apps to Space, Quick Save Apps to Space, Toggle Space Map, Restart SpaceAtlas, and Toggle Test Mode have no shortcut until you give them one.

While the placement prompt is showing, ↩ assigns or applies, ⎋ means Later, and the number keys pick a space by its number. The rest of the time these keys reach your apps as usual.

Select an action to see what it does, then add, change, or remove its keyboard shortcuts and gestures. The bindings in this screenshot are customised; the defaults are listed on the left.

Import / Export

Save your setup before experimenting or moving to another Mac.

• Export — choose what to include: profiles, keyboard shortcuts, Nexus Art and menu bar settings, advanced settings, app assignments, and general settings.
• Import — choose which parts of a file to bring in. An imported profile replaces an existing profile with the same name.
• Automatic backup — every import first saves a backup of your current settings. Revert… restores one of those backups.

Logging

Use the Logging tab when you need more visibility into what SpaceAtlas is doing.

• Log Level — from Debug (Everything) to Error (Critical Only).
• Retention (days) — how long log files are kept, 1 to 30 days. Older files are removed automatically.
• Open Log Folder and Delete All Logs.
• Debug — Test mode simulates space switching with no desktop change, so you can try out a layout safely.

Advanced

• Timing & Performance — timing presets from Ultra Fast to Ultra Slow, with sliders for switch settle time, cooldown, and more.
• Window Behavior — hiding apps when you leave a space, following focused and fullscreen windows, restoring window layouts, and the launch prompt.
• Menu Bar — the Keep Awake timer and the menu bar grid colours.
• Fine-tuning — optional macOS settings SpaceAtlas works better with.
• Trackpad & Mouse Gestures — switch gestures off or change the swipe distance.
• Keystroke Display — show the keys you press on screen, useful for demos and recordings.
• Reset — Reset All Data… starts over.

Signing in

1. Open Settings and go to the Account tab.
2. Enter your email address and click Send Code. A 6-digit code is sent to your inbox. If it does not arrive, Resend Code becomes available after a short wait.
3. Enter the code and click Verify Login.

Authorization Status

The Account tab shows your trial or license status at the top — green when licensed, orange during a trial or grace period, red when sign-in is required — along with the email you are signed in with. Software Updates further down shows the installed version.

When you are signed in

• Refresh Status — re-checks your license and trial status with the server.
• Manage Account — opens your account page on the SpaceAtlas Labs website, where you can manage devices, download updates, and renew.
• Logout — signs you out of SpaceAtlas on this Mac.
• Deactivate Device — removes this Mac from your license, freeing a seat for another machine.

The Account tab is your central place for signing in, checking your license status, and managing this Mac's activation.

Licenses

Each license shows its status, seat usage, activation and expiry dates, and your last payment. Key details at a glance:

• Seats — how many devices are active out of the number your license allows.
• Activated / Expires — when your license was activated and when it expires.
• Devices — each activated Mac with its Device ID, when it was last seen and activated, its macOS version, and its app version. The Mac you are using is marked. Click Remove to deactivate a device and free a seat.

A Space Suite license lists each app separately, with its own seats, devices, and download.

Updates and Downloads

• Download — gets the newest version your license entitles you to. If you own an older version, the page shows both your Owned Version and the Latest Eligible one.
• Update Status — whether your updates are active, in a grace period, expired, or ready for renewal.
• Renew Updates — extends your update eligibility for your current license.

Your account page is the central place to manage devices, download updates, and renew your license.