Quickstart

Vortex is an agentic coding platform for macOS. You describe the work; Vortex understands your workspace, writes an editable plan, edits across files, runs commands, and verifies the result.

This page takes you from an invite to a finished, reviewed change.

1. Join the beta and install

Vortex is in a closed beta on macOS. Windows and Linux are not part of this beta.

• Requirements: macOS 12 or later. Apple Silicon is recommended; Intel is supported.
• Get an invite: add your email to the waitlist. Invites are sent as places open.
• Download: sign in with GitHub at app.usevortex.dev and download the installer for your Mac.
• Install: open the DMG and drag Vortex to Applications. Builds are Developer ID signed and notarized, so Gatekeeper accepts a fresh download without workarounds.

After the first launch, the app checks the beta update channel and installs new builds in place — you do not re-download a DMG for every release. See Install and updates for the channel details.

2. Sign in and open a workspace

The desktop app requires a one-time GitHub sign-in, which authorizes the device and keeps the beta invite list meaningful. Vortex then sends only a minimal heartbeat (app version, OS, architecture, last-seen timestamp). Workspaces, code, prompts, and chats are never transmitted.

Add a workspace as a folder on your Mac. 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.

3. Connect a model

Vortex provides the agent loop and workspace control; you provide the model. Open Settings → Models and add one of:

• an OpenAI, Anthropic, or OpenRouter API key;
• any OpenAI-compatible endpoint (self-hosted, gateway, or a provider that speaks the same API);
• an optional local GGUF model that runs on your Mac through the local model path.

Provider costs stay yours, and requests go directly from your Mac to the provider you chose. Models and keys covers helper-model pools and how to keep cheap models for routine steps.

4. Run the loop

The loop is always the same: understand → plan → implement → verify.

1. Pick a mode. Ask, Plan, Agent, or Debug. Start in Plan mode for anything non-trivial.
2. Describe the outcome. Write the job the way you would brief a colleague: what should be true when it is done, and which checks must pass.
3. Attach context if you want it. Retrieval runs on-device; add files or folders explicitly when you know where the work lives.
4. Review the plan. Plan mode writes an editable plan file into .vortex/plans/. Read it, edit it, then let the agent work. See Plan files.
5. Watch the run. Edits, terminal commands, and browser steps stream into the transcript, with the files they touch.
6. Approve the diffs. In Review mode every agent edit is staged as a pending patch. Nothing lands on disk until you approve it. See Review mode.
7. Check the result. Ask for a verification command (for example npm test) and require a specific exit code or output phrase.

A concrete first job

Plan a change that adds a `--dry-run` flag to the CLI's `deploy` command.
Keep the existing flags working, add a test for the new flag, and show me
the plan before you edit anything.

Then, once the plan looks right, switch to Agent mode with the same wording plus "implement the plan you just wrote" — or press the plan's build action.

Where things live on disk

~/.vortex is local only. Override its location with VORTEX_HOME.

Keyboard shortcuts worth knowing

• ⌘K — command palette: open a workspace, switch mode, report a bug.
• Hold ⌘ — reveal the shortcuts available in the current surface.
• Go menu — jump to any file, view, URL, or job from the tab bar.

Next steps

• Install and updates — beta channel, notarization, and the DMG fallback.
• Plan files — shape the approach before the agent edits anything.
• Review mode — approve or reject each patch.
• Models and keys — BYO providers, local models, helper pools.
• Headless CLI — vortex run and vortex review in CI or over SSH.