Getting started
Install and updates
Install the Vortex macOS beta, sign in with GitHub, follow the Beta update channel, and find logs, config, and a clean uninstall path.
Vortex is a desktop app for macOS. The install is a signed DMG, and after that the app updates itself on the Beta channel with a single restart. This page covers the install, the one-time GitHub sign-in, what leaves your Mac, and how to uninstall.
Before you install
- Operating system: macOS 12 or later. Apple Silicon is recommended; Intel is supported.
- Out of scope: Windows and Linux are not part of this beta.
- Build line: the current beta is around 0.2.0-beta.52.
- An invite: the beta is closed, so add your email to the waitlist and wait for the invitation.
Get the installer
- Join the waitlist at /#beta if you have not already.
- When you are invited, sign in with GitHub at app.usevortex.dev/account.
- Download the DMG for your Mac from that account page.
Builds are Developer ID signed and notarized, so Gatekeeper accepts a fresh download without any workaround. If macOS asks you to confirm an unrecognised developer, you are probably running an old build — download the current DMG again from the account page.
Install and launch
- Open the DMG and drag Vortex to Applications.
- Launch Vortex from Applications.
- Sign in with GitHub in the app.
That sign-in is a one-time device authorization using the OAuth device flow at app.usevortex.dev/device. The token is stored locally at ~/.vortex/account.json with mode 0600. It keeps the beta invite list meaningful; it is not used to read your repositories.
What the app sends
Vortex sends only a minimal heartbeat: app version, operating system, architecture, and a last-seen timestamp. Workspaces, code, prompts, and chats are never transmitted. Cloud model requests go straight from your Mac to the provider whose key you supplied.
Open your first workspace
Add a folder as a workspace. The first root you add is only the default working directory; a workspace can hold several roots, and Vortex treats them as one job surface. From there the loop is always the same: understand, plan, implement, verify. The Quickstart walks through a first job, and Plan files covers the plan step.
Update channels
Settings → About → Update channel selects where the app looks for builds.
| Channel | Feed | Status |
|---|---|---|
| Beta | https://usevortex.dev/updates/latest-beta.json | Active during the closed beta |
| Stable | https://usevortex.dev/updates/latest.json | Present in the updater; not selectable in this beta |
Beta is the active channel. You do not re-download a DMG for each release.
Installing an update
Updates download in the background and install with a single restart.
- Settings → About shows the last time the app checked and the current install progress.
- After a restart, the About panel shows whether the new build landed.
- If an in-app update fails, Vortex falls back to the DMG referenced by the signed manifest. Install that DMG exactly like the first one.
Where things live
| Path | What it holds |
|---|---|
~/.vortex/vortex.db | Saved workspaces, chat sessions, runs, traces, pending review patches |
~/.vortex/logs/vortex.log | App-level event log, rotated at 4 MB with one .1 backup |
~/.vortex/logs/feedback.jsonl | Feedback and bug-report records, one JSON object per line |
~/.vortex/mcp.json | MCP server configuration |
~/.vortex/account.json | Device session token, mode 0600 |
~/.vortex/detached/<id>/ | Status and traces for detached vortex run jobs |
<repo>/.vortex/ | Repo-owned rules, memory, skills, plans, canvases, notepads |
~/.vortex is local only. Set VORTEX_HOME to move that whole directory, for example onto an encrypted volume or into a different user account. VORTEX_MCP_CONFIG overrides the MCP config path on its own.
Uninstall
- Quit Vortex.
- Remove Vortex from Applications.
- Remove
~/.vortexif you want a clean slate — it holds the database, logs, the account token, and per-workspace checkpoints. - Remove
<repo>/.vortex/from any repository where the agent wrote plans, canvases, or memory.
Steps 3 and 4 are optional. Keeping ~/.vortex preserves your saved workspaces and sessions; keeping a repo's .vortex/ preserves its plans and memory.
Troubleshooting
I have not been invited yet
The beta is closed, so the app cannot be downloaded without an invite. Add your email to the waitlist and wait for the invitation email; the account page is only available to invited testers.
Gatekeeper questions an old build
Fresh downloads are signed and notarized and open without a prompt. If macOS warns about an unrecognised developer, the DMG is old or was copied from somewhere other than the account page. Download the current build from app.usevortex.dev/account.
The update channel looks wrong
Beta is the active channel in this beta. If you see no updates, confirm Settings → About → Update channel is set to Beta and check the last-checked time in the same panel. A manual DMG install always works if the in-app path is stuck.
Reading the logs
Open ~/.vortex/logs/vortex.log. It rotates at 4 MB and keeps one .1 backup, so check both files for a crash that happened a while ago. You can also use ⌘K → Report a bug, or Settings → General → Diagnostics & feedback, to send a report with a debug snapshot. Crash reporting is opt-out; create the ~/.vortex/disable_telemetry flag file to turn it off.
Next steps
- Quickstart — from invite to a finished, reviewed change.
- Models and keys — add a provider key before your first run.
- Review mode — approve or reject each patch.
Get an invite
Vortex is in a closed beta on macOS. Add your email to the waitlist to get an invite and a download link.