> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/user-guide/installation/auto-update.md).

# Auto-Update

Orbitron includes a built-in auto-update system that keeps your installation up-to-date automatically. This guide explains how the auto-update system works and how to configure it.

## 🎯 Key Features

### Default Settings

* **Default:** Auto-update offers an interactive choice during installation and is **disabled** by default if not selected (opt-in approach)
* **User Control:** Can be enabled/disabled at any time
* **Safe Updates:** Downloads in the background and applies on next execution

### Update Process

1. **Automatic Check:** Checks for new versions every 6 hours (when enabled)
2. **Background Download:** Automatically downloads new versions when available
3. **Apply on Next Run:** Downloaded versions are automatically applied the next time you run Orbitron
4. **No Interruption:** Does not interrupt your current work

## ⚙️ Configuring Auto-Update

### Configure via CLI Commands

```bash
# Enable auto-update
orbitron config set autoUpdate true

# Disable auto-update
orbitron config set autoUpdate false

# Check current setting
orbitron config get autoUpdate

# View all settings
orbitron config list
```

### Configure via Environment Variable (Temporary)

You can temporarily control auto-update using environment variables:

```bash
# Enable auto-update (current session only)
export ORBITRON_AUTO_UPDATE=true

# Disable auto-update (current session only)
export ORBITRON_AUTO_UPDATE=false
```

### Priority Order

Auto-update settings are applied in the following order:

1. `ORBITRON_AUTO_UPDATE` environment variable (highest priority)
2. `autoUpdate` setting in `~/.orbitron.json` file
3. Default value based on installation method

## 🔒 Safe Updates

Orbitron ensures safe updates by:

* **Verified Downloads:** All binaries are verified with checksums to ensure safety
* **Conflict Prevention:** Automatically prevents multiple concurrent updates
* **Automatic Rollback:** Preserves the previous version if an update fails

## 🚨 Critical Update Notifications

When there are critical security patches or required updates, an update notification will be displayed when running Orbitron and **the program will automatically terminate**:

```bash
$ orbitron

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Critical Update Required
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

New version v0.1.13 has been released.
This update includes critical security patches.

Update with the following command:

# Automated installation (recommended)
curl -fsSL https://orbitron.megaone.com/api/install.sh | bash

[Program will automatically terminate]
```

**Important:**

* For critical update notifications, the current version of Orbitron cannot be run until the update is completed
* After updating, you can use it normally

## 🔄 Manual Update with `/update` Command

You can manually check for and install updates using the `/update` command within Orbitron's interactive mode:

### Usage

```
/update
```

### How It Works

The `/update` command provides on-demand update checking and installation:

1. **Version Check**: Checks for the latest available version (bypassing the 6-hour cooldown)
2. **Smart Detection**: Identifies three possible states:
   * Already on latest version
   * Update already downloaded (ready to apply on restart)
   * New update available for download
3. **Background Download**: Downloads updates asynchronously without blocking your work
4. **Apply on Restart**: Downloaded updates are applied the next time you run Orbitron

### Update Messages

| Status                 | Message                                                      | TTL              |
| ---------------------- | ------------------------------------------------------------ | ---------------- |
| **Already Latest**     | "Already on the latest version"                              | 2 seconds        |
| **Already Downloaded** | "Update v{version} is already downloaded. Restart to apply." | Persistent       |
| **Downloading**        | "Downloading update v{version}..."                           | Up to 10 minutes |
| **Download Complete**  | "Update completed: v{version}. Restart to use new version."  | 2 seconds        |

### Technical Details

The `/update` command:

* Forces an immediate version check (ignores cooldown period)
* Uses file-based locking to prevent concurrent updates
* Verifies downloads with SHA256 checksums
* Supports platform-specific installation

## 🛠️ Troubleshooting

### If Auto-Update Is Not Working

1. **Verify auto-update is enabled:**

   ```bash
   orbitron config get autoUpdate
   ```
2. **Try manual update with `/update` command:**
   * Open Orbitron in interactive mode
   * Type `/update` and press Enter
   * Wait for the download to complete
   * Restart Orbitron to apply the update
3. **Update manually via installation script:**

   ```bash
   # Install the latest version
   curl -fsSL https://orbitron.megaone.com/api/install.sh | bash
   ```

## 🔗 Related Documentation

* [Installation Guide](/orbitron-docs/user-guide/installation.md) - How to install Orbitron
* [Migration Guide](/orbitron-docs/user-guide/installation/migration-guide.md) - Upgrade from legacy versions
* [Troubleshooting](/orbitron-docs/user-guide/installation/troubleshooting.md) - Common issues and solutions