Proxyma Enterprise Server

Semantic search and AI chat over your own documents, on your own infrastructure. This manual covers installing, configuring, operating and using the server edition.

Which license it takes

Proxyma Enterprise Server activates Enterprise licenses, and no others.

The editions do not share licenses. A Personal or Professional license is refused here, and the server stays on Community limits; use it on Proxyma Home Server, or write to contact@proxyma.ai about Enterprise. An Enterprise license is refused on Proxyma Desktop and Proxyma Home Server.

What Proxyma is

Proxyma indexes uploaded files, Jira, Confluence, Bitbucket, SVN, Windows network shares, SharePoint, Microsoft Teams and Outlook, and answers questions in plain language with citations to the source documents.

• Your documents stay where you put them. Proxyma runs on your hardware, and Proxyma Enterprise Server sends no diagnostics, and under an Enterprise license no answer ratings.
• You choose the model, per deployment. With a local Ollama instance no document text leaves your network, though the assistant's web searches still reach a search engine. Anthropic, OpenAI, Mistral, DeepSeek, Azure OpenAI and Google are also supported.

Before you install

What you need

Java, Node, Python, Maven and a browser are not needed on the host.

What you do not need to decide yet

AI provider, sources and users are all set later from the web interface.

Installing

Download the compose bundle, proxyma-enterprise-server-<version>-compose.tar.gz (about 17 KB), from the releases page, and run the installer:

curl -LO https://github.com/proxyma-ai/proxyma-releases/releases/download/v<version>/proxyma-enterprise-server-<version>-compose.tar.gz
tar -xzf proxyma-enterprise-server-<version>-compose.tar.gz
cd proxyma-enterprise-server-<version>
./install.sh

1. The first run creates .env and stops. Edit it - see "The one decision" below.
2. Run ./install.sh again. It pulls the image, starts the stack, and reports success once Proxyma answers on its port.

Re-run ./install.sh to apply any configuration change. It sets HOST_UID and HOST_GID to your account on every run, but never overwrites another value you have set, never regenerates an existing signing key, and never deletes your data.

To control when you upgrade, pin a version in .env instead of tracking latest, using a version from the releases page:

PROXYMA_IMAGE=ghcr.io/proxyma-ai/proxyma-enterprise-server:<version>

Installing without a registry

If the host cannot reach a container registry, save the image on a connected machine:

docker pull ghcr.io/proxyma-ai/proxyma-enterprise-server:<version>
docker save ghcr.io/proxyma-ai/proxyma-enterprise-server:<version> | gzip > proxyma-enterprise-server.tar.gz

Load it on the host, set PROXYMA_IMAGE in .env to that tag, and run ./install.sh:

docker load < proxyma-enterprise-server.tar.gz

The postgres, tls and office profiles pull their own images, so use COMPOSE_PROFILES= with your own database and proxy.

The one decision

At the top of .env:

COMPOSE_PROFILES=postgres,tls,office

The shipped .env enables the bundled PostgreSQL, the bundled TLS termination and Office Files. Keep only what your host does not already have:

office lets the assistant create and edit Word, Excel and PowerPoint files. Its container is built on the host and needs internet once. Without it, an empty value is supported: Proxyma runs as a single container.

Using your own PostgreSQL

Point PROXYMA_DB_URL at any database the container can reach:

PROXYMA_DB_URL=jdbc:postgresql://db.internal:5432/proxyma
PROXYMA_DB_USER=proxyma
PROXYMA_DB_PASSWORD=...

Create the database with the pgvector extension enabled:

CREATE DATABASE proxyma OWNER proxyma;
\\c proxyma
CREATE EXTENSION IF NOT EXISTS vector;

Using your own reverse proxy

Leave tls out of COMPOSE_PROFILES. Proxyma then publishes the web interface and API on one loopback port, 127.0.0.1:4246 by default, for your proxy to forward to.

Three settings matter; the first two are required.

nginx

location / {
    proxy_pass http://127.0.0.1:4246;
    proxy_http_version 1.1;

    # REQUIRED. Proxyma builds single sign-on redirect URLs from these.
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # REQUIRED for chat. Answers stream token by token.
    proxy_buffering off;
    proxy_read_timeout 3600s;

    client_max_body_size 200M;
}

Caddy

proxyma.example.com {
	reverse_proxy 127.0.0.1:4246 {
		flush_interval -1
		transport http {
			read_timeout 3600s
		}
	}
	request_body {
		max_size 200MB
	}
}

Traefik

labels:
  - traefik.enable=true
  - traefik.http.routers.proxyma.rule=Host(`proxyma.example.com`)
  - traefik.http.routers.proxyma.tls=true
  - traefik.http.services.proxyma.loadbalancer.server.port=4246

Traefik forwards X-Forwarded-* and does not buffer responses by default, so it needs neither required setting added.

Set PUBLIC_ORIGIN in .env to the URL people will type. It is used for cross-origin rules and single sign-on redirects.

First start

Open the URL and create the first administrator account. There is no default account or password.

1. Configure an AI provider - Settings, then AI Providers. Nothing works until one is reachable. Then choose the chat model in Agents and the embedding model in Search; the AI Providers tab lists what is left.
2. Point Proxyma at your servers - Settings, then Connections. Add a connection for each Jira, Confluence, Bitbucket or SVN server you read from.
3. Add a source - Sources, then Connect. Start with one small folder or project.
4. Ask a question - the chat page. If the answer cites your document, the installation is complete.
5. Add people - they create an account from the sign-in page, or sign in with single sign-on. Manage accounts in Administration, then Users.

Choosing an AI provider

Settings → AI Providers. Proxyma needs two kinds of model, which can come from different providers:

Choose the chat model in Settings → Agents and the embedding model in Settings → Search.

Local models

With an Ollama instance, no document text leaves your network, though the assistant's web searches still reach a search engine.

Hosted models

Anthropic, OpenAI, DeepSeek, Mistral, Azure OpenAI and Google are supported. The passages retrieved for each question are sent to that provider's API.

Seeing what it costs

Settings → Usage & Cost, an administrator's tab, shows what model calls cost over the period you choose: a chart over time, and totals by provider, model and service. Logs, below it, lists every call - when it ran, which part of the product asked for it, the model, the tokens including cache writes and reads, and what it cost - for every user. Administration → Usage & cost breaks the same spending down per user. A Super Admin can Clear log: the deployment's monthly limit counts these calls, so this month is counted again from zero; each user's own quota is not reset.

Costs are estimated from the rates you set on the provider, not taken from your provider's bill. A model with no rate configured counts as $0 and is marked.

Connecting sources

1. In Settings → Connections, choose Add connection for each Jira, Confluence, Bitbucket or SVN server you use: a name, the server URL and your access token (for SVN, your user name and password). Choose Test to check it.
2. On each connection, choose whether the assistant may read and write through it.
3. In Sources → Connect, choose the connection, then register the projects, spaces, repositories and folders to index.

You can add several connections of the same kind, for example a production and a test Jira. The first one is the default; the assistant uses it unless a source or the conversation names another. To move a source to another connection, open its Configure dialog.

Each source is indexed on a schedule you set. A re-sync processes only documents that changed.

For an SVN repository, a network share or a SharePoint site, choose which file types to index when you connect it, or later in its Configure dialog. With none chosen, a network share or SharePoint site indexes every supported type, and an SVN repository a built-in list of document, text and source-code types.

An SVN repository or a network share has an Include subfolders switch, like a folder. In its Configure dialog it is Scan subdirectories recursively.

Network shares

1. Optionally, a Super Admin limits which file servers may be used, in Settings → Network → Allowed file servers. With none listed, any server may be.
2. Each user adds a Network share connection in Settings → Connections: the file server, and their own domain user name and password.
3. In Sources → Connect → Network Share, enter the network path.

Files are read as their owner's account, so only what that account can open is indexed. A network share source cannot be shared. A password the file server rejects is not retried until it is changed.

Microsoft 365: SharePoint, Teams and Outlook

1. A Microsoft 365 administrator registers an app in Microsoft Entra ID with the redirect URI https://<your server>/api/v1/microsoft/oauth/callback and the delegated permissions Sites.Read.All, Files.Read.All, Mail.Read, Mail.Read.Shared, Calendars.Read and Calendars.Read.Shared.
2. A Super Admin enters its tenant ID, client ID and client secret in Settings → Network → Microsoft 365.
3. In the same section, turn on the sources your organization allows: Teams channels, Teams chats, Outlook mail and calendars. SharePoint needs no switch.
4. In Settings → Connections, add a Microsoft 365 connection and choose Sign in. Add one per account if you use more than one.
5. In Sources → Connect, choose SharePoint Site, MS Teams Channel, MS Teams Chats or Outlook Mail or Calendar.

Everything is read with the account of the person who added it, and cannot be shared. Teams chats are indexed as one document per chat per day, in UTC. A calendar indexes every meeting from 365 days back to 365 days ahead (set in Settings → Network), and a recurring meeting lists each of its dates.

Credentials are encrypted before storage, with the key in a file in data/ that only its owner can read. They are never written to logs, and always masked in the interface.

Watching an index run

Each document moves through DETECTED → QUEUED → DOWNLOADING → CONVERTING → EMBEDDING → COMPLETED. A failed document lands on FAILED with the reason, and the run continues.

Users and permissions

Conversations are isolated per user, and so are uploaded files and their derived indexes unless their source is shared. Managing another user's account does not give access to their chat history. Any signed-in user can look up other users by name or email when sharing a key account.

Single sign-on

Google, GitHub and Microsoft are supported alongside email and password, which keeps working either way. Set the client ID and secret in .env and re-run ./install.sh.

Using Proxyma

Chat

Ask in plain language. Proxyma answers from retrieved passages and cites them. If nothing relevant is indexed, it says so instead of inventing an answer.

Answers stream as they are produced. If they arrive all at once, see Troubleshooting.

Search

Proxyma combines keyword matching (BM25) with semantic similarity and fuses the rankings, so both exact error codes and vague descriptions find the right document.

The knowledge graph

Proxyma can extract the things each document mentions - a component, a service, a parameter, a person - and the relationships between them into a graph. The same thing mentioned in two files becomes one node.

It is off until you turn it on in both places:

1. Settings → Search - switch knowledge-graph extraction on and choose the extraction model. With no model chosen, nothing is extracted.
2. If extraction keeps timing out, raise Extraction timeout in the same place. A model running on your own hardware often needs several minutes per passage.
3. Per source - in the source's settings, turn on Build a knowledge graph. What the source has already indexed is extracted in the background. Nothing is re-indexed. Only sources you opt in are extracted.

Turning it off deletes that source's graph. Its index and search stay as they are.

To view it, open a source and click the graph icon in its header.

• Drag to rotate, scroll to zoom, shift-drag to pan. Larger, brighter points have more connections.
• Click a point to select it and see its links; click a linked point to step through the graph.
• The top-left controls set the relationship depth shown, the spacing, auto-rotation, and reset the view.
• Stars sets how many points to draw, most connected first. A large source is clearer and faster with a few hundred; raise it to see the long tail.
• A large graph is drawn as it loads, most connected first, so you can read it before it has finished loading.

Turning it off for a source deletes what that source put into the graph. Anything another source also contributed stays.

Key accounts

Key accounts is a shared workspace for reviewing an important client: how healthy the account is, and what to do next to keep and grow it. A team works on it together. The assistant reads the sources you link and proposes facts and ratings, each with its evidence, and next moves. Facts, ratings and moves stay proposals until a person confirms them. The assistant's other changes - details, people, opportunities, risks, actions and revenue - are saved as it makes them, after your approval in Ask mode.

Create an account

1. Open Key accounts in the top bar and click New account.
2. Enter the name, tier, goal, renewal date and ARR, then click Create account. You become its Owner, and its first review opens.
3. On Overview, fill in the other details. Each field is saved when you leave it.
4. Under Sources for the assistant, link the indexed sources that hold the account's contracts, tickets, minutes and revenue. With none linked, the assistant asks you to link them.

Linking a source gives nobody access to it. A member who cannot read a source sees it named and still cannot search it.

Share it and choose roles

1. On the account, click Share.
2. Search for people by name or email, choose a role, and click Add.

Members see each other's changes as they happen. If someone saved a field after you opened it, your save is refused and their value is shown. Removing a member keeps their past work on record. A Super Admin can read every account, and change only the ones they are a member of.

Run a review with the assistant

1. Open the assistant panel with the assistant button at the right of the account's header.
2. Choose Run the health review, or ask in your own words. The assistant reads the linked sources, using sub-agents in parallel.
3. Its proposals appear on the tabs: facts on Profile, ratings on Health, stakeholders on People, opportunities and risks on Opportunities.
4. On Health, open each question. Read the proposed rating, its reasons and its evidence. Choose your rating from 1 to 5 and click Confirm and continue. If it differs from the proposal, say why.
5. On Profile, check each fact against its source and verify it.

The assistant cannot confirm a rating, decide a move, sign the report, change members, delete anything, or record how a stakeholder feels about you. Its writes follow the permission mode chosen in the panel, as in chat.

Read the dashboard

Overview shows six numbers: the health score (0-100, from confirmed ratings only), ARR and its change, days to renewal, whitespace value, sponsor coverage and plan progress. Click a number to open what is behind it. The charts show health by dimension across reviews, revenue against plan by month, the whitespace, the stakeholder map and the moves.

To fill the revenue chart, click Import revenue and paste a CSV with a month column, an actual column and, optionally, a plan column. Or ask the assistant to import a revenue sheet from a linked file source.

Decide the moves and keep the plan

1. Ask the assistant to Draft next moves. Each move on Next moves shows its case, evidence, impact and confidence, highest priority first.
2. For each move, click Accept and give it an owner and a due date, Reject it with a reason, or Defer it. Within a review, a rejected move is not proposed again unless the assistant says what changed.
3. Accepted moves become actions on Plan. Update their status there. To track an action in Jira, click Create a Jira issue with the assistant and send the message it prepares; the Jira write follows the panel's permission mode.

Write and sign the report

1. On Report, click Ask the assistant to draft it, or write it yourself.
2. Edit the draft and click Save draft.
3. The Owner clicks Sign. After that nobody can edit it, the assistant included. Use Copy the report or Print to send it on.

Activity lists every change by a person or the assistant: who, when, and the value before and after. To review the account again, click New review. Confirmed ratings carry over as the baseline, and open actions carry over.

The API and MCP

Everything the interface does is available over a REST API, and MCP-capable editors and agents can search your indexed documents directly. See Search API and MCP for the endpoint reference and an MCP client configuration.

Administration

Administration has five sections, all open to Admins and Super Admins.

Operating

docker compose logs -f proxyma-server   # logs
docker compose ps                       # status
docker compose down                     # stop
./install.sh                            # apply a config change, or upgrade

Backups

With the bundled database, Proxyma runs continuous archiving with pgBackRest. With your own PostgreSQL it takes pg_dump snapshots instead; keep your own backups in place.

To restore a backup:

1. Open Administration → Operations → Backups.
2. Choose Restore next to the backup and type its file name to confirm.

A restore overwrites all current data, and Proxyma is unavailable to everyone until it finishes.

Moving settings to another server

Settings → Import & Export copies the configuration to another Proxyma installation as a JSON file. It works as the desktop manual describes, with these differences here: only a Super Admin can use it, it carries only their own connections, and user accounts, API tokens and Microsoft 365 sign-ins are never exported. It is not a backup.

Upgrading

Proxyma Enterprise Server does not update itself. It updates its database schema on start.

If you installed from the registry:

1. Back up the database.
2. If you pinned a version in PROXYMA_IMAGE, change it to the new version, or the pull re-fetches the old one.
3. Pull and restart:

docker compose pull proxyma-server
docker compose up -d

Name the service: a bare docker compose pull fails on the locally built database image.

If you installed without a registry:

1. Back up the database.
2. Load the new image as in "Installing without a registry", and set PROXYMA_IMAGE to it.
3. Run ./install.sh.

Troubleshooting

It does not answer on its port

Run docker compose logs proxyma-server. The cause is nearly always the database: an unreachable host, a wrong password, or missing pgvector.

Single sign-on redirects to http:// and fails

Your reverse proxy is not sending X-Forwarded-Proto. Add the header; the provider itself is not misconfigured.

Chat answers appear all at once, or seem to hang

Your reverse proxy is buffering the response. In nginx, set proxy_buffering off.

A company AI service fails with a certificate error

If the log says PKIX path building failed, the service is signed by a certificate authority the container does not know. A Super Admin pastes it, in PEM form, under Settings → Network → Custom CA Certificate.

Uploads fail on large files

Raise the body size limit in your proxy. Proxyma itself accepts 200 MB.

Let's Encrypt will not issue a certificate

Applies only to the bundled tls profile.

1. Make the hostname resolve to this host from the public internet, with ports 80 and 443 reachable.
2. Behind Cloudflare, set SSL/TLS mode to Full (strict).
3. If issuance still fails, set the DNS record to DNS-only until the certificate is obtained, then re-enable proxying.

The container restarts, or runs out of memory

Proxyma needs about 4 GB. If the bundled database is also running, lower PG_SHARED_BUFFERS or move the database to another host.

Search returns nothing useful

Check in Sources that indexing completed for each document. If you changed the embedding model after indexing, reindex everything.

Uninstalling

docker compose down          # stop, keep everything
docker compose down -v       # stop and delete named volumes

Neither removes data/ or keys/. Delete the directory yourself.

Getting help

Include the output of docker compose logs --tail 200 proxyma-server, your COMPOSE_PROFILES value, and whether you use your own PostgreSQL or reverse proxy.