Installing on Windows

Windows provides a one-click installer: a self-contained single EXE that bundles Axiomate together with offline Git and Python packages. Follow the wizard to complete the installation.

System requirements

• Operating system: Windows 10 (build 10240 or later) or Windows 11
• Architecture: x64 (arm64 and 32-bit are not supported)
• Required dependency: Git 2.40+ (the installer installs bundled Git 2.54 if missing)
• Extra Windows 10 dependency: Windows Terminal (if missing, the installer installs Microsoft.WindowsTerminal online through winget)
• Optional dependency: Python 3.12+ (some skills are Python scripts; install as needed — the installer offers it as an option)

The installer requires administrator privileges and applies two system settings unconditionally: it sets the PowerShell execution policy to RemoteSigned and enables Windows Developer Mode, and it adds the install directory to the system PATH. Note this on managed enterprise machines.

Installation steps

Download the installer from the download page (named like axiomate-installer-<version>-windows-x64.exe) and double-click to run. Windows will prompt for permission (administrator rights are needed to write to the install directory and system settings); click "Yes" to open the setup wizard.

The installer is currently unsigned, so Windows SmartScreen may warn you on first run. Select "More info → Run anyway" to proceed.

The wizard has the following steps:

1. Welcome

Shows the installer version and the bundled Axiomate version, and lists what the installer will do. Language selection (中文 / English) is available only on this page and cannot be changed later.

If a previous Axiomate install is detected, clicking "Next" prompts for confirmation, after which the installer uninstalls the old version before continuing: it clears the system PATH, deletes the desktop and start-menu shortcuts, removes the registry entry, and deletes the old install directory (a progress indicator is shown during this step). This does not delete ~/.axiomate.json or ~/.axiomate/, so your personal config and data are preserved.

2. Environment check

Automatically detects the operating system, architecture, Windows Terminal, Git, and Python:

• OS and architecture: must be Windows 10+ and x64. The wizard cannot continue otherwise.
• Windows Terminal: checked only on Windows 10. If it is missing, the installer requires it and installs Microsoft.WindowsTerminal online through winget so Axiomate shortcuts can open in a terminal; Windows 11 usually includes it, so this check is skipped there.
• Git: if 2.40+ is already installed, this is skipped; if missing, bundled Git 2.54 is installed (required, cannot be unchecked).
• Python: if 3.12+ is already installed, this is skipped; if missing, installing bundled Python 3.12 is checked by default but can be unchecked. Uncheck it to save time if your usage doesn't need Python skills.
• pip mirror: appears only when "install bundled Python" is checked. Enabled by default using the Tsinghua TUNA mirror; you can switch to Aliyun or turn it off. Keep the default on networks in China; turn it off on networks elsewhere.

3. Install location

Defaults to %USERPROFILE%\axiomate. Note:

• The target directory is wiped before installation. If the chosen directory is non-empty, the wizard asks for confirmation and then deletes its entire contents — never point it at a directory containing project code or documents.
• System directories (Windows, Program Files, ProgramData, etc.), special user folders (Desktop, Documents, Downloads, etc.), and the ~/.axiomate config directory are all blocked.
• Use the default path or create a dedicated empty directory.

4. Options

All options can be adjusted as needed. Even if you turn them all off, the axiomate command is still installed and usable:

• Quick model config: lets you enter a model and API key on the next step. During installation this overwrites ~/.axiomate.json. Existing users should back up their model config first, or leave it unchecked and add a model via the first-run flow after install.
• Clear Axiomate config directory: when checked, the installer deletes the entire ~/.axiomate/ directory during installation, including existing sessions, settings, skills, and other data, with no backup. Unchecked by default. Axiomate is still in beta, so if you hit old-data compatibility issues when upgrading, check this to clear the old data; back it up first if the directory contains important data. Note that this option does not delete the ~/.axiomate.json config file — if that file is also incompatible, check "Quick model config" to overwrite it, or delete it manually after installation.
• Enable bypass permission mode by default: writes to ~/.axiomate/settings.json so the AI can run commands and edit files automatically without asking each time. This significantly reduces safety guardrails; enable it only on trusted personal or isolated environments, and keep it off on enterprise, production, or shared machines.
• Create a default workspace and shortcuts: creates desktop and start-menu shortcuts that launch the Axiomate TUI in the workspace directory — convenient for first-time users. When checked, you can customize the workspace directory (default %USERPROFILE%\axiomate-workspace).

Registering the system PATH is the default behavior and cannot be disabled.

5. Model config (only when "Quick model config" is checked)

Quick config currently supports the following providers and primary models:

After choosing a model, enter the corresponding platform API key (required; it must not contain the * character). To use another provider or custom model, edit ~/.axiomate.json after installation.

6. Progress and finish

The progress page runs each step in order with a live log; on failure it turns red and points to the log file. After completion:

• If you created a workspace, you can click "Launch Axiomate" or use the desktop / start-menu shortcut.
• If you did not, open a new terminal so the PATH takes effect, then run axiomate.

Verification

Open a new terminal (already-open windows must be reopened to pick up the PATH change) and run:

axiomate --help
git --version

If both commands print output, the installation succeeded. If you installed Python, you can also run python --version to confirm.

Uninstalling

The installer registers a standard uninstall entry, so remove it through the built-in system entry points:

• Settings → Apps → Installed apps, find Axiomate, and click Uninstall; or
• Control Panel → Programs → Uninstall a program, and select Axiomate.

This runs the installer's bundled uninstaller, which removes the install directory, cleans up the system PATH, and deletes shortcuts and the registry entry.

Your personal data is preserved: ~/.axiomate.json, ~/.axiomate/, and the workspace directory are left untouched. Delete them manually if you want a full cleanup.