Skip to main content
This guide explains how to run Sovara with Palantir Foundry as the enterprise data backend and how to use Palantir AIP for embeddings. In this setup, agent SDKs, the CLI, and the Sovara UI still connect to Sovara Server. Sovara Server can run on a desktop during development, or on customer-managed infrastructure such as Azure, AWS, GCP, Kubernetes, or an internal VM in production. Foundry is used behind Sovara Server for ontology storage, governed writes, and embedding requests. Sovara clients connect to Sovara Server, which can run locally or in customer infrastructure. Sovara Server uses a storage backend interface with SQLite, MongoDB, PostgreSQL, and Palantir options. The Palantir backend connects to AIP embeddings, Foundry Ontology, and Actions or Functions. Sovara clients connect to Sovara Server, which can run locally or in customer infrastructure. Sovara Server uses a storage backend interface with SQLite, MongoDB, PostgreSQL, and Palantir options. The Palantir backend connects to AIP embeddings, Foundry Ontology, and Actions or Functions.

​
What Foundry provides

When you select the Palantir backend:
  • Foundry Ontology stores the Sovara objects used by runs, tool calls, annotations, and project state.
  • Ontology Actions and Functions apply Sovara writes to Foundry.
  • AIP embedding endpoints create embeddings for Sovara’s internal algorithms and workflows.
  • Sovara Server remains the integration boundary. Runners and desktop clients do not write directly to Foundry.
Other Sovara storage backends, such as SQLite, MongoDB, and PostgreSQL, remain available. Choose Palantir when your organization wants Sovara data represented in Foundry.

​
Prerequisites

You need:
  • A Sovara enterprise server, an enterprise desktop build, or the publicly available desktop app for development, which includes Palantir support natively.
  • Access to the Sovara Foundry ontology setup. To get access, contact Sovara Labs.
  • Your Foundry host, for example https://example.palantirfoundry.com.
  • The ontology API name provided during the Sovara Foundry setup.
  • The Foundry branch to use, usually main.
  • A Foundry token with access to the Sovara ontology, the required Actions or Functions, and the AIP embedding endpoint.

​
Configure the Foundry backend

Use the Sovara settings UI when configuring a desktop or interactive server deployment:
  1. Open Sovara Settings.
  2. Go to the database backend settings.
  3. Set Database backend to Palantir Ontology.
  4. Set Foundry Host to your Foundry stack URL, for example https://example.palantirfoundry.com.
  5. Set Ontology API Name to the value provided during the Sovara Foundry setup.
  6. Set Branch to the Foundry branch, usually main.
  7. Paste the Foundry token into Token.
  8. Click Test connection.
  9. Save the settings.
For a server deployment, the same backend can be configured with environment variables: 
export SOVARA_DB_BACKEND="palantir"
export SOVARA_PALANTIR_HOST="https://example.palantirfoundry.com"
export SOVARA_PALANTIR_ONTOLOGY_API_NAME="<ontology-api-name>"
export SOVARA_PALANTIR_BRANCH="main"
export SOVARA_PALANTIR_TOKEN="<foundry-token>"
If you store server configuration in ~/.sovara/config.yaml, use the equivalent keys: 
db_backend: palantir
palantir_host: https://example.palantirfoundry.com
palantir_ontology_api_name: <ontology-api-name>
palantir_branch: main
palantir_token: <foundry-token>

​
Configure Palantir embeddings

Sovara can use Palantir as the embedding model vendor. This sends embedding requests through Foundry’s OpenAI-compatible AIP endpoint.
  1. Open Sovara Settings.
  2. Go to the model settings for embeddings.
  3. Set the embedding vendor to Palantir.
  4. Set Foundry Host to your Foundry host, for example example.palantirfoundry.com.
  5. Use text-embedding-3-small as the model unless Sovara Labs provided a different model name for your Foundry environment.
  6. Paste the same Foundry token into Foundry token, or use a separate token with AIP embedding access.
  7. Save the model settings.
The Palantir model entry is for embeddings. Configure chat and reranking models separately if your deployment uses different providers for those tiers.

​
Verify the setup

After saving both backend and embedding settings:
  1. Connect the Sovara UI, CLI, and agent runners to that server.
  2. Run a small agent workflow from a connected project.
  3. Confirm that the run appears in the Sovara UI.
  4. Queue or create an annotation recommendation and confirm that retrieval uses the configured embedding model.
If Sovara reports that Palantir rejected the token, create a new Foundry token from your stack’s token settings page and replace the token in Sovara settings. The token settings page is usually: 
https://<your-stack>/workspace/settings/tokens
If the connection test fails for another reason, check the Foundry host, the ontology API name, the selected branch, and whether the token has access to the Sovara ontology and embedding endpoint.