Install SoAI Core

Use the platform path below for a normal SoAI Core installation. The Linux, macOS (experimental), and Windows network installers resolve the latest stable release from the Releases section of the official SoAI repository, validate the expected artifact identity, size, and checksum, and install it into the standard SoAI location. The Linux network installer also authenticates its signed release manifest and archive inventory. The macOS and Windows bootstraps checksum-verify their downloads; use the signed release verifier below when independent publisher authentication is required.

Choose and verify a platform

These are SoAI Core paths. SoAI OS is a separate private appliance edition with its own artifact and launcher. See SoAI products and editions before choosing a deployment.

Confirm the host requirements

The minimum and recommended CPU, memory, storage, and GPU specifications are listed in Requirements. Model files, plugin backends, databases, user files, and working space need capacity beyond the application installation. A hard disk drive (HDD), SD card, or USB drive can host SoAI, but these options are not recommended and do not satisfy the SSD-based storage tiers.

Understand the network and privilege requirements

Installing a third-party component for a user and redistributing that component inside the SoAI installer are different legal acts. SoAI installs packages, runtimes, browser artifacts, and optional backends that remain under their owners' licenses; the SoAI license cannot grant redistribution rights for them. SoAI does not have permission to repackage every dependency, and other licenses impose redistribution conditions that vary by component and build. A complete bundled installer would itself redistribute all of those works. SoAI therefore includes a third-party component only when its redistribution rights and notice obligations are satisfied, and otherwise downloads it from its supported source so the component is supplied under its own terms.

Because third-party runtime dependencies must be downloaded under their respective licenses rather than bundled, an initial installation requires a temporary internet connection. The network installer retrieves the current SoAI release metadata and the correct platform artifact, then the installed launcher provisions the managed Python environment and the third-party dependencies and runtime artifacts that cannot be included in the release payload. It can also use the host package manager for missing system prerequisites. Backends, models, and optional feature assets are obtained separately when you choose them. After everything required for your deployment is present, SoAI can operate without public-network access as described in Offline installation and operation.

Network installers retry temporary download failures. On Linux and macOS, archive downloads can resume from saved data. On Windows, the installer shows where it saved diagnostic logs for download attempts; keep those logs when reporting a failed installation.

On Linux, root or sudo access is required by the standard installer because it writes the system-owned /opt/soai installation, creates the /usr/local/bin/soai command, installs missing host packages when necessary, and, if automatic startup is selected, writes and manages /etc/systemd/system/soai.service. sudo is only the elevation mechanism for those host changes; it is not required merely to use the WebUI. An extracted, verified release can instead be installed to a user-writable target without --fast when the host prerequisites are already installed, but that path does not install a system service or the global soai command.

Verify a release before installation

Download only the platform artifact named by the release. GitHub-generated source snapshots are not runnable release or update artifacts. For signed release sets, verify the manifest signature, pinned public-key fingerprint, artifact checksum, and archive inventory before execution. See Download and verify SoAI releases for the complete procedure.

Install SoAI Core

Run the network installer:

curl -fsSL https://soai.to/install/linux | bash

Unless SOAI_INSTALL_AUTOSTART is set, the installer asks Start SoAI automatically at system startup? [y/N]. No is the default. An unrecognized response, no interactive terminal, or no response within 30 seconds leaves automatic startup disabled. Selecting Yes requires a running systemd service manager.

The network installer adds soai to the system command path. Run it from any directory; it uses /opt/soai as its working directory and accepts the same commands and options as soai.sh. On a host with multiple installations, this command belongs only to the default /opt/soai installation. Start another installation through its explicit launcher path; its installer and uninstaller do not replace or remove the default installation's command.

To request service installation and automatic startup during an unattended installation:

curl -fsSL https://soai.to/install/linux | SOAI_INSTALL_AUTOSTART=y bash

From an extracted and verified Linux release, choose an explicit target:

./install-soai-from-release.sh --target /path/to/soai

On supported Debian and Ubuntu hosts, the fast path installs required system packages, installs to /opt/soai, configures and enables soai.service, starts the service, and verifies its health. It obtains root privileges through sudo when needed:

./install-soai-from-release.sh --fast

Without --fast, the installer provisions the selected application target and its managed runtime but does not claim ownership of system service supervision. Start and manage that installation through its ./soai.sh launcher.

Complete local source trees use install_soai_from_release.sh and install_soai_from_release.bat. Release archives retain the hyphenated installer names. Completed installations and successful updates use underscore filenames.

Install on Windows

Setup requests administrator privileges and enables the operating system's long-path support before preparing its managed runtime. The complete-archive launcher uses the same preparation. Choose a concrete installation folder; setup rejects links, unsafe path components, conflicting launcher configuration, and installations with unfinished update recovery before replacing application files. Long paths remain subject to the limits of external backends and operating-system tools. If one of those tools rejects a path, use a shorter location for the affected backend or model.

If setup fails while preparing SoAI, it shows where diagnostic logs were saved. Keep that folder when asking for help, even if setup removes the incomplete installation.

Run the verified SoAI-<version>-windows-x64-setup.exe, or use the network bootstrap below. The native installer copies the application, prepares its managed runtime, creates the registered uninstall entry and shortcuts, then offers Start SoAI on the finish page. The executable is currently unsigned. When downloading it directly, authenticate it with the signed release manifest before approving the operating-system warning. The network bootstrap instead validates the release metadata and checksum before starting the same setup.

Set-ExecutionPolicy Bypass -Scope Process -Force; irm https://soai.to/install/windows | iex

The setup executable is the standard installed-app and update path. As an alternative, verify and extract SoAI-<version>-windows-x64-complete.zip, open its SoAI folder, and run:

install-soai-from-release.bat --target C:\path\to\SoAI

The archive includes the compiled soai.exe launcher. Its installer bootstraps the app-local runtime, copies the managed application payload to the selected target, and provisions dependencies there. Use --silent for a non-interactive install. Use soai.exe for lifecycle and runtime-repair commands after installation. Do not substitute a Linux complete archive or a generated source snapshot for either Windows artifact.

Install on macOS (experimental)

On Intel or Apple silicon macOS, run:

curl -fsSL https://soai.to/install/mac | bash

The installer targets /Applications/SoAI. Unless SOAI_INSTALL_AUTOSTART is set, it asks Start SoAI automatically at system startup? [y/N]. No is the default. An unrecognized response, no interactive terminal, or no response within 30 seconds leaves automatic startup disabled. Selecting Yes requires the launchctl and plutil launchd tools.

The same installer is included in the published macOS complete archive and can be run locally. The WebUI supports application updates from the manifest-authenticated macOS release artifact. It does not expose SoAI GPU telemetry or tuning on macOS. Local backends can still use their own Metal support.

Finish installation and first-run setup

SoAI provisions its own Python 3.13 runtime and required application artifacts instead of modifying the system Python environment. A network-connected first installation downloads dependencies and browser artifacts that are absent from the payload. Subsequent launches reuse that managed runtime. On Linux and macOS, the launcher also checks whether its own runtime needs a security update and completes that update before starting SoAI. This can require a download even on an existing installation.

Expect that first provisioning to take several minutes rather than seconds. It prepares the managed Python environment and then installs runtime artifacts in turn, among them the Playwright Chromium build, a managed Java runtime, the Apache Tika server, and a token encoding cache, and the launcher names each one as it starts. How long it runs depends on the connection and the host, so read the launcher output rather than a clock: a step that is still downloading is working, not stuck. The WebUI does not exist yet during this phase, which is why the address the launcher prints appears only once provisioning finishes.

If first installation is interrupted, close any active installer and retry the launcher or run install-deps to complete the managed runtime. If SoAI reports that lock recovery is required, retain its diagnostics and obtain support before removing lock or transaction files.

From a stopped installation, install-deps provisions or repairs the runtime without starting SoAI:

./soai.sh install-deps

On Windows, use soai.exe install-deps. Prepare all runtime and model dependencies before enabling offline mode; see Offline installation and operation.

Start the installed edition

On Windows, start SoAI from the SoAI entry the setup executable writes to the Start Menu and the desktop, which runs the launcher and shows the WebUI in its own application window without a terminal or a browser. On Linux and macOS, run the launcher from a terminal:

SoAI on Linux:    soai
SoAI on macOS:    sudo /Applications/SoAI/soai.command

Running the launcher without a command starts the application. Use --start-no-browser when it must not open a browser, which the Windows launcher never does in any case. The default backend port is 5090; the configured TLS state determines whether the printed URL uses HTTP or HTTPS. Never use the Core launcher to manage a SoAI OS installation.

On Windows, the application runs in a background service that starts when a SoAI window opens and stops after the last window closes and SoAI stops. It does not start with Windows and needs no administrator prompt for any user. Every user can start SoAI, but only administrators and the service can read or change its data folder. Each Windows user signs in separately in the SoAI window. Keep model, file, and backup folders on local drives: the service uses the computer account, so network shares and mapped drives that need a user's saved credentials are unreachable, and the system health check reports such settings as network_paths.

The Windows lifecycle and repair commands run through the same soai.exe, which a default installation places in C:\Program Files\SoAI without adding it to the command path, so run them from a terminal opened in the installation folder or by the launcher's full path.

Complete first run

1. Open the SoAI WebUI at the URL printed by the launcher.
2. Follow the account steps in the setup wizard to create the first Administrator.
3. Follow SoAI setup in the wizard to connect a provider or install a local engine and model, then select Chat once a model is ready.
4. If you skipped SoAI setup, open Plugins to install an inference backend, add a model through Models, and send a short test message in Chat.

Before the first user exists, normal application and compatible API routes remain unavailable. After account creation, the /v1 surface remains open until an Administrator creates the first API key. Review Authentication and API keys before making the server reachable from another host.

Related documentation

• SoAI quickstart
• Deploying SoAI Core
• Launcher and CLI reference
• Network and TLS
• Uninstall SoAI Core