Deploying SoAI Core

This guide turns a working SoAI Core installation into a durable private service. SoAI OS has a separate appliance lifecycle and launcher.

Choose a supported deployment path

HostRecommended pathBoundary
Debian 12 or 13, or Ubuntu 24.x or 26.xUse the official installer or a verified complete archive with ./install-soai-from-release.sh --fast.The fast path installs required packages, targets /opt/soai, configures soai.service, starts it, and verifies readiness. It requires root and systemd.
Other 64-bit LinuxInstall a verified complete archive to an explicit target and operate it with ./soai.sh.This path is outside the supported operating-system set. Provide your own dependencies and service supervision.
Windows 10 or 11 on x64Run the verified SoAI-<version>-windows-x64-setup.exe.The executable is currently unsigned, so authenticate it with the signed release manifest before approval. The installer owns application setup, managed runtime preparation, shortcuts, and removal.
macOS (experimental) on Intel or Apple siliconRun curl -fsSL https://soai.to/install/mac | bash or use the installer from a verified macOS archive.The installer can configure launchd startup, and application updates use the manifest-authenticated macOS complete archive.

Start with Install SoAI Core and verify downloaded artifacts as described in Download and verify SoAI releases. Do not deploy a GitHub-generated source snapshot as a runnable release.

Configure the deployment

  1. Start SoAI and open the SoAI WebUI at the URL printed by the launcher. The default port is 5090.
  2. Follow the account steps in the setup wizard to create the first Administrator.
  3. Follow SoAI setup in the wizard, or add a local backend or remote provider yourself, then send a test message in Chat.
  4. Create a backup before changing network exposure or moving data paths.

Before the first account exists, normal application and compatible API routes are unavailable. Do not place an incomplete wizard behind a shared endpoint.

Set the private network boundary

Use Network and TLS to set the listening address, port, certificates, allowed hosts, and trusted proxy networks. A reverse proxy must preserve WebSocket upgrades for /api/v1/system/ws and avoid buffering compatible API streams. A proxy does not make public internet exposure a recommended configuration.

Complete Hardening checklist before allowing other hosts to connect. Create at least one API key before exposing /v1/* beyond loopback: after setup the compatible API is open while the key store has no records, and creating the first key turns authentication on.

Plan capacity and storage

Keep the database, encryption key, model store, plugin environments, file storage, knowledge indexes, logs, and backups on durable storage sized for their workloads. Use Data storage, retention, and relocation before changing a path and Capacity planning before increasing request concurrency. A fast model does not remove disk, queue, backend, or provider limits.

If you use a notebook as a server, keep it connected to power and disable automatic sleep in the operating system's power settings. Disable sleep on lid closure if you intend to close it; where the notebook cannot stay awake with the lid closed, leave it open. Check from another device that SoAI remains reachable when idle and, if you close the lid, while it is closed.

Operate and verify the deployment

Verify after each deployment change

  1. Run ./soai.sh status on Linux, sudo /Applications/SoAI/soai.command status on macOS, or soai.exe status on Windows. Confirm that it identifies the intended installation.
  2. Request GET /api/v1/system/health on the configured scheme, host, and port.
  3. Sign in through the final client URL and confirm live status updates. A page that retains old values while disconnected must show them as stale.
  4. Call GET /v1/models with the same authentication policy clients will use, then send one bounded inference request.

Related documentation