Docs › Get started › Updates
Updates
How AstraCode updates itself, the settings that control it, and how to update from a terminal.
On this page
- How it works
- What each install does
- The status bar
- Settings
- Checking now
- Ignoring a version
- Linux packages
- Updating from a terminal
- Where updates are kept
- If something goes wrong
AstraCode looks for new versions on its own and, where it can, downloads them in the background. It never restarts by itself: the new version is installed only when you choose Restart and Update.
How it works
- The editor checks for a new version shortly after it starts, every 30 minutes after that, and when you come back to the window, but never more than once every 10 minutes on its own.
- When a version is out, the status bar shows Update available and the download starts, with its progress in the status bar.
- When the download is ready, the status bar shows Update ready and a notification says AstraCode X is ready to install.
- Choose Restart and Update. AstraCode quits, puts the new version in place, and opens again. Unsaved files are handled as on any quit.
Every update is checked before it is installed: it must match the checksum published with it, and on macOS and Windows it must be signed by the same publisher as the copy you have. If a check fails, nothing changes.
What each install does
| Installed from | How it updates in the editor |
|---|---|
macOS .dmg or Homebrew | Downloads and is verified in the background; installs when you choose Restart and Update. |
| Windows installer | Downloads and is verified in the background; Restart and Update runs the new installer and reopens AstraCode. The system installer shows the administrator prompt. |
Linux .tar.gz, extracted as you | Downloads and is verified in the background; installs when you choose Restart and Update. |
Linux .deb or .rpm | Your package manager owns it. The notice's Update now upgrades it through apt or dnf. See Linux packages below. |
| Windows zip, or a copied folder | Cannot update itself. Install with the installer from the download page. |
The status bar
| Status bar | Meaning | Press it to |
|---|---|---|
| Update available | A new version exists. | Check now and get the update. AstraCode: Check for Updates does the same. |
| Update ready | The new version is downloaded. | Restart into it. |
| Update needs you | It could not be installed automatically. The tooltip says why. | See the options. |
Settings
astracode.updates.mode chooses how much the editor does:
| Value | What happens |
|---|---|
automatic (default) | Check, download in the background, and offer Restart and Update. A copy that cannot update itself behaves as notify. |
notify | Check, and tell you when a version is out: AstraCode X is available. You have Y. with Download, What's new (when the release has notes) and Ignore this version. |
off | Do not check. |
The older setting astracode.updates.check is still honoured: false means off.
Checking now
- Run AstraCode: Check for Updates, or choose Check for Updates in AstraCode Settings, General.
- The editor says AstraCode X is the latest version., or starts downloading the new one, or offers to restart into one already downloaded.
Ignoring a version
Choose Ignore this version on the notification, and AstraCode stops offering that version. It asks again when the next one comes out. A check you run yourself with Check for Updates forgets the choice and offers it again. Later just closes the notification; the status bar keeps saying Update ready.
Linux packages
A copy installed from a .deb or .rpm belongs to your package manager, so the editor never swaps its files. When a version is out, the notice offers Update now: it opens a terminal in the editor and upgrades AstraCode through apt or dnf, which asks for your password. Restart AstraCode when it finishes.
If the machine does not have the AstraCode apt or dnf repository yet, the first update adds it, so later versions also arrive with your system's own updates. The same happens when you run astracode-update in a terminal.
Updating from a terminal
Each platform has one update command. Every one of them accepts --check, which says what is available and changes nothing, and every one works even when the editor will not start.
| Installed from | Command |
|---|---|
| macOS | astra -update, once you have run AstraCode: Install 'astra' Command in PATH. Without it: /Applications/AstraCode.app/Contents/Resources/app/bin/astracode -update |
| Windows | astracode -update in PowerShell or Command Prompt. The installer puts astracode on your PATH; open a new terminal after installing. |
Linux .deb or .rpm | astracode-update, or astracode -update |
Linux .tar.gz | ./bin/astracode -update from the folder you extracted, as the user who owns it |
Terminal
astra -update # macOS: update if a newer version is out
astra -update --check # say what is available, change nothing
The terminal update makes the same checks as the editor; if one fails, nothing is installed. Close AstraCode before updating it from a terminal.
Where updates are kept
Downloads wait in ~/Library/Caches/AstraCode/updates on macOS and Linux, and %LOCALAPPDATA%\AstraCode\updates on Windows. The editor clears old ones itself. Update messages are written to the AstraCode MCP output channel; open it with AstraCode: MCP: Show Connection Log.
If something goes wrong
- Could not install automatically: no permission to replace the application. On macOS 14 and later, allow AstraCode under System Settings, Privacy & Security, App Management, or run
astra -updatein Terminal. - Could not reach the update feed. Try again in a moment. The network, a VPN or a proxy is blocking
astracode.io. <folder> is not writable by this user, so it cannot update itself.The Linux tarball was extracted withsudo. Extract it again as yourself.- The installer was cancelled. The Windows administrator prompt was declined. Choose Try again.
Every message, with its fix, is in Install and update problems.
← The chat panel Tab completion →
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems