Download vsa-installer
Download it, run it, and you have a working VSA machine: git, PHP 8.3, Composer,
Node, the extensions and the vsa command. Nothing to configure first,
and running it again updates rather than reinstalls.
Version 1.1.1 · released 2026-09-25
Windows
Your machineRun it
-
Double-click it
Open it straight from the folder it landed in — usually
Downloads. No terminal, no command to type.Unzip first. Double-clicking
vsa-installer-macos.zipunpacks it in place, leavingvsa-install.commandnext to it. macOS needs the zip: a file downloaded over the web arrives without its executable bit, and Terminal refuses to run it without one.Then double-click
vsa-install.command. A Terminal window opens and the install runs in it. It asks for your Mac password only if Homebrew needs to be installed, and for your GitHub token once.The first time, macOS will refuse to open it. The file came from the internet and is not signed, so Gatekeeper stops it. Go to System Settings → Privacy & Security, scroll to the message about
vsa-install.command, and click Open Anyway. Once per download.Double-click
vsa-install.cmd— nothing to unpack. A console window opens and the install runs in it. Everything is per-user through Scoop, so you never need administrator rights.Your browser may ask you to confirm the download first; Windows treats every
.cmdthat way.The first time, Windows will warn you. SmartScreen shows “Windows protected your PC” because the file is downloaded and unsigned. Click More info, then Run anyway. Once per download.
Both prompts are what an unsigned download looks like on a current OS — they are not a sign anything is wrong. If you would rather skip them entirely, use the one-line command further down instead: a script piped from the network is never quarantined, so neither OS asks.
-
Open a new terminal
The PATH change only reaches a shell that starts after the install.
Terminalvsa doctor # is anything still missing? vsa new acme-hr --name="Acme HR" --app=hr # a project from the template cd acme-hr && vsa serve # run it
Or run it without downloading
Same installer, straight from this site — nothing left in your Downloads folder, and no security prompt to clear. This is what the double-click file does for you.
Terminal
curl -fsSL https://vsa.vectorasoft.com/vsa-installer.sh | bashPowerShell
& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing https://vsa.vectorasoft.com/vsa-installer.ps1).Content))
If it asks for a GitHub token. The installer checks GitHub first
and only asks when it has to, so this step disappears by itself if the VSA
repositories are ever made public. While they are private it asks once for a
token and remembers it — in the macOS
keychain or Windows Credential Manager, never in a git remote URL. Make one in
GitHub under Settings → Developer settings → Fine-grained tokens →
Generate new token, with resource owner vectorasoft-org,
repository access all and permission
Contents: Read-only; an organisation owner then approves it.
Finish in one command
Options go at the end, so a new machine and a running app are a single line. On macOS
append them after | bash -s --; on Windows after the closing )).
Terminal
curl -fsSL https://vsa.vectorasoft.com/vsa-installer.sh | bash -s -- --new acme-hr --name="Acme HR" --app=hr| macOS | Windows | What it does |
|---|---|---|
--postgres | -Postgres | Also install a local PostgreSQL 16 server |
--new <folder> | -New <folder> | Finish by creating a project from the template, then set it up |
--clone <git-url> | -Clone <git-url> | Finish by cloning an existing project and running vsa setup |
--token <token> | -Token <token> | Instead of the VSA_TOKEN environment variable |
--ref <branch> | -Ref <branch> | Install a CLI branch other than main |
--dir <folder> | -CliDir <folder> | Put the CLI somewhere other than ~/.vsa/cli |
--new and --clone take everything after them, so they come last.
What it installs
- git, if the machine has none, and your token stored in the OS keychain or Credential Manager
- PHP 8.3 with the extensions the framework needs, and Composer
- Node, and the
vsacommand itself, cloned into~/.vsa/cli - PostgreSQL 16, only with
--postgres
On macOS it uses Homebrew; on Windows, Scoop, per-user. The token is written to your Composer configuration and the credential store — never into a git remote URL, and never passed on a command line where other users could read it.
Verify what you downloaded
A script you pipe into a shell is worth checking. Compare the SHA-256 against the published sums — these are also in SHA256SUMS.txt and version.json.
| File | SHA-256 |
|---|---|
vsa-installer-macos.zip | see SHA256SUMS.txt |
vsa-install.cmd | see SHA256SUMS.txt |
vsa-installer.sh | see SHA256SUMS.txt |
vsa-installer.ps1 | see SHA256SUMS.txt |
Check it
# macOS
shasum -a 256 ~/Downloads/vsa-installer-macos.zip
# Windows
Get-FileHash $HOME\Downloads\vsa-install.cmd -Algorithm SHA256If something goes wrong
“No GitHub token.” The installer normally asks for one, so this means
it had no terminal to ask from — a CI job, or a shell with no TTY. Set
VSA_TOKEN in the environment, or pass --token /
-Token, and it will not prompt at all.
404 when cloning. The token is valid but has no access to
vectorasoft-org — usually a fine-grained token an organisation owner has
not approved yet.
macOS, a Rosetta terminal. The installer cannot restart itself out of Rosetta, so it stops and tells you. Open a normal terminal and run it again.
Windows, “running scripts is disabled”. Run the downloaded file as
powershell -ExecutionPolicy Bypass -File .\vsa-installer.ps1, or use the
one-line command above, which is not affected.
Anything else. vsa doctor reports the tools, the PHP
extensions, the .env keys it needs (never their values), the git hooks and
whether the database, XAuth and the CDN are reachable.