SoAI quickstart

This guide takes an installed SoAI Core from first launch to a working answer: start the process, create the first administrator, connect one model source, then send a test message in the SoAI WebUI and repeat it over the compatible API. Install SoAI Core covers the packages, platform paths, and release verification that come before any of this.

Start SoAI and open the WebUI

On Windows the installer registers the application with the desktop, so open SoAI from the Start Menu folder of the same name or from the desktop shortcut and the launcher starts SoAI and shows the WebUI in its own application window, which needs neither a terminal nor a browser. That shortcut runs soai.exe, which a default installation places in C:\Program Files\SoAI and does not add to the command path, so the lifecycle commands in this documentation need a terminal opened in the installation folder or the launcher's full path.

On Linux and macOS (experimental), open a terminal and run the launcher for your installation.

# SoAI on Linux, installed with the network installer, from any directory
soai

# SoAI on Linux, from the installation folder
./soai.sh

# SoAI on macOS
sudo /Applications/SoAI/soai.command

The network installer puts soai on the system command path as a link to the launcher of the installation it created, and the launcher resolves that link and works from its own installation folder, so you can type soai anywhere and reach the same application, with the same commands and options that soai.sh accepts. An installation unpacked from a release archive has no such command, so run its ./soai.sh from the installation folder. On a host carrying more than one installation, soai belongs to the default one in /opt/soai and the others need their explicit launcher paths.

Running the launcher without a command starts the application and opens the WebUI in your default browser, so pass --start-no-browser when it must not, or turn SERVER.WEBUI.AUTO_OPEN_BROWSER off to change that for every start. The default port is 5090 and TLS stays off until you configure it, which makes the first address http://localhost:5090. If something else already holds 5090 while SERVER.HTTP.NETWORK.PORT is still at its default, SoAI logs the conflict and moves up through the fallback range ending at 5099 instead of refusing to start, while a port you set explicitly is treated as a requirement and a conflict there stops startup, so run soai --status when you need the address a running instance is actually serving.

The Windows launcher loads that same address into its own window rather than a browser and never opens one, which makes --start-no-browser and SERVER.WEBUI.AUTO_OPEN_BROWSER inert there. The window is the WebUI, so anything the documentation describes doing in a browser tab you do in it, and you can still reach the running instance from a browser on the same host or from another machine when the configured network binding allows it.

A first launch reaches that address slowly, because the installation still has to provision its managed runtime and the artifacts that come with it, which takes several minutes on a normal connection. The launcher names each step while it works. Later launches reuse what it prepared and start in the time you would expect. Install SoAI Core covers that phase and what to do when it is interrupted.

These commands drive SoAI Core. A SoAI OS appliance has its own launcher at ./soai_os/soai_os.sh, and Launcher and CLI reference covers the remaining lifecycle and diagnostic commands.

Create the first administrator

A database with no users opens the setup wizard instead of the sign-in page. The welcome step carries the interface language selector, the license step shows the controlling document with its fingerprint and records your acceptance, and the use declaration step asks how the deployment will be used. Personal use is the only declaration you can select on SoAI Core, and choosing it skips the product access step, so a Core installation reaches the account form one step after the declaration. Licensing administration describes the entitlement paths and the controls a deployment sees once it holds one.

The account form takes a username of 3 to 50 ASCII letters, numbers, dots, underscores, or hyphens, a password of 8 to 1,024 characters, and the same password again in Confirm password. SoAI stores the username in lowercase, gives the account the Administrator role, and applies the language you picked on the welcome step as its interface language. Creating the account signs you in and continues to SoAI setup. If automatic sign-in fails, the wizard opens the sign-in page instead. See Users, roles, and sessions for later account management and Passwords and credential tools before choosing the administrator password.

If setup finishes in another browser window, the waiting wizard moves to sign-in. Sign in separately in each browser.

Until the first administrator account exists, protected API requests return 403 with setup_required, including requests under /v1. The health, system information, system limits, and license routes stay public throughout, so a monitoring probe can still tell that the process is up while setup is pending.

Set up AI in the wizard

Setup waits for hardware and backend discovery before showing recommendations. If discovery fails, select Try again. A detected GPU alone does not guarantee acceleration; install a compatible backend runtime.

SoAI setup helps you prepare a first model. Under Where should your AI run?, choose On this device, Cloud providers, or both. If local setup is unavailable, the wizard explains why and recommends a cloud provider.

  1. On Get ready, enter a provider's API URL and API key, then select Connect. For a local model, use Automatic (recommended) to let SoAI choose an engine, or select Choose manually. This step is skipped when you chose only local models and a suitable engine is already installed.
  2. On Choose a model, select a suggested model or use Search for another model. Suggestions show download size and estimated reply speed. Models from a connected provider appear in their own list.
  3. Follow installation and download progress on Getting everything ready. SoAI tests local models before marking them ready. For a provider model, select Send a test message to check that it answers.
  4. Select Chat once a model is ready. Chat opens a trial conversation with that model selected, tools turned off, and the SoAI system prompt turned off. You can change these conversation settings in Chat configuration after trying the model.

Select Skip SoAI setup on the first step to use the manual setup instructions below. On a later step, Skip keeps your progress while installations and downloads continue. When Chat offers Finish SoAI setup, select it to return to the remaining steps. If no model is ready, Enter SoAI opens your default page.

Connect a model

Use this route to add a local inference engine yourself if you skipped SoAI setup or want another engine. The controls below need Plugin read access (PLUGIN_READ), Plugin administration (PLUGIN_ADMIN), Model read access (MODEL_READ), and Model administration (MODEL_ADMIN).

  1. Open Plugins and find the engine you want, such as Ollama. A bundled plugin that is compatible with the host arrives enabled, so its card switch reads Enabled, and the card status tells you whether the backend itself is present, where Not installed means there is nothing to run yet.
  2. Select Install backend on that card, choose a build that matches the host, then select Start installation.
  3. Open Models, select Add model, then use Download model to fetch one through the plugin, or Add model manually to register files already on disk, which is available only to an Administrator.
  4. Follow the download or registration task in Tasks. SoAI runs model discovery after a successful backend installation, so a local model reaches the catalog once discovery finds it.

Adding your first backend compares the bundled engines and explains when one of these controls is hidden, and Bundled plugins reference describes what each plugin is for.

Connect a remote OpenAI-compatible provider

A model that already runs behind an OpenAI-compatible API needs no local backend. Open Models, select Add model, then Add provider, choose External, and enter a Provider name, API URL, API key, and an optional Models filter before selecting Add provider. SoAI asks the service for its model list and adds the models it accepts. Adding a provider requires Plugin administration (PLUGIN_ADMIN).

Send the first message

Open Chat, pick the model in the selector, and send a short message. The sidebar keeps Chat and Automation hidden until this browser has seen at least one model that is loaded or available and is not an embedding model, then leaves them in place from that point on, so an instance whose only model is an embedding model shows no Chat entry at all.

When the model is missing from the selector, check its status in Models, confirm the owning plugin or provider in Plugins, and look at the operation in Tasks. For a failed backend or provider request, open Logs from the Settings button at the right of the header, which is where Logs lives because the default sidebar layout hides Settings, About, and Logs, and reading it requires Log access (LOG_ACCESS). Monitoring and observability covers the log controls.

Call the same model over the API

The compatible API serves the same catalog on /v1/chat/completions. After setup it stays open until the first API key exists, and creating one makes bearer authentication mandatory on both the OpenAI-compatible and Anthropic-compatible routes, so leave the Authorization line out of the example below while the instance still has no keys. To create one, select the Settings button at the right of the header, choose Settings, then OpenAI, a tab that appears only to an Administrator with API key management (OPENAI_API_ADMIN). 

curl http://localhost:5090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"model": "YOUR_MODEL", "messages": [{"role": "user", "content": "Hello"}]}'

Change a Core setting

Select the Settings button at the right of the header, choose Settings, then select Advanced in the page header, which an Administrator with Configuration changes (CONFIG_PATCH) can see. Use Search settings... to find the field, change it, and select Save in the page header. Configuration lists every current path with its default and description, and Configuration scopes and restart behavior explains which saves reach the running process and which wait for a restart.

Related documentation