Skip to main content
On-prem deployments split Sovara into three parts:
  • sovara-server runs on a server managed by your team.
  • The Python or TypeScript runner is installed where the agent process runs.
  • The Remote desktop app runs on the laptop or workstation used to inspect runs.
The server is the only shared backend. The desktop app, CLI, SDKs, and VS Code extension call that server over HTTPS and websockets.

​
Installation

​
1. Install the server on your server

Run the private sovara-server Docker image on the machine that should own Sovara data. This is usually a Linux VM, Kubernetes node, or internal container host with network access from agent machines and desktop users. Download the Docker image archive from the protected Sovara enterprise download page. Choose the archive for the server CPU architecture, usually Linux Intel/AMD. 
curl -L -o sovara-server-<version>-linux-x64.tar.gz "<server-archive-url>"
curl -L -o checksums.txt "<checksums-url>"
sha256sum -c checksums.txt --ignore-missing
Load the image into Docker: 
gunzip -c sovara-server-<version>-linux-x64.tar.gz | docker load
Start the server: 
docker run -d \
  --name sovara-server \
  --restart unless-stopped \
  -p 5959:5959 \
  -v sovara-data:/var/lib/sovara \
  sovara-server:<version>
Verify it from the server: 
curl http://127.0.0.1:5959/health
Then verify it from an agent machine or desktop machine: 
curl http://<server-host>:5959/health
Use a reverse proxy, firewall rule, or private network route appropriate for your environment. The desktop and runners need access to the REST API and the websocket endpoint on the same server.

​
2. Install the runner where the agent runs

Install the runner in the same environment as the agent process. This is often the same server as sovara-server, but it can be any machine that can reach the server URL. For Python agents, install the Python SDK: 
uv add sovara
or: 
python -m pip install sovara
Install the Sovara CLI for recording and inspection commands: 
curl -fsSL https://apps.sovara-labs.com/cli/install.sh | sh
Connect each agent project folder from the project settings setup command: 
sovara connect-agent \
  --project-root /path/to/agent/project \
  --server-url http://<server-host>:5959 \
  --project-id <project-id> \
  --agent-token <agent-token>
Then run the agent normally from that project folder. For TypeScript agents, install the TypeScript runner in the agent project: 
npm install @sovara/runner
TypeScript runner support should follow the same project-folder connection model: project id in .sovara/.project_id, server URL and agent token in OS credential storage. Until that lands, use the Python SDK path for enterprise smoke tests. The runners should send enough project, run, and code-version metadata to the server; the server should not need direct access to the agent source tree.

​
3. Install the Remote desktop app

Download the Remote desktop installer from the protected Sovara enterprise download page. Choose the installer for the user’s operating system and CPU architecture:
  • macOS Apple Silicon: Sovara-remote-<version>-arm64.dmg
  • macOS Intel: Sovara-remote-<version>-x64.dmg
  • Windows: Sovara-remote-<version>-Setup.exe
  • Linux Debian/Ubuntu Intel/AMD: Sovara-remote-<version>-x64.deb
  • Linux Debian/Ubuntu arm64: Sovara-remote-<version>-arm64.deb
  • Linux Fedora/Red Hat Intel/AMD: Sovara-remote-<version>-x64.rpm
  • Linux Fedora/Red Hat arm64: Sovara-remote-<version>-arm64.rpm
The Remote desktop app bundles the web UI, but it does not include or start sovara-server. It only connects to the server URL configured for that user.

​
4. Configure the Remote desktop app

  1. Open the Remote desktop app.
  2. Enter the server endpoint, for example http://10.0.10.25:5959 or https://sovara.internal.example.com.
  3. Click Connect.
The desktop app stores this endpoint in its local desktop configuration. Agent runners are connected separately with sovara connect-agent from project settings.

​
Updates

Server updates are handled by the system administrator. Download the new Docker archive, load it, and redeploy the container using your normal deployment process. Desktop app updates use the Remote desktop update channel. End users update the desktop app; they do not update the server. Runner updates happen in the agent environment:
  • Python: update the sovara package.
  • TypeScript: update @sovara/runner.
  • CLI: rerun the Sovara CLI installer or install a pinned version.