Proxyma Server

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

What Proxyma is

Proxyma connects to the places your organisation already keeps its knowledge - file shares, Jira, Confluence, Bitbucket, SharePoint, Teams, SVN - indexes what it finds, and lets people ask questions in plain language. Answers cite the documents they came from.

Two things distinguish it from a hosted AI search product:

• Your documents stay where you put them. Proxyma runs on your hardware. Nothing is uploaded to us, and there is no telemetry of document content at any tier.
• You choose the model. Point Proxyma at a local Ollama instance and no text leaves the building at all. Point it at Anthropic, OpenAI, Mistral, DeepSeek, Azure OpenAI or Google and it uses those instead. This is a per-deployment setting.

Before you install

What you need

Proxyma does not need Java, Node, Python or Maven installed on the host - they are all inside the container image. It does not need a browser either: web page rendering uses a pure-Java engine, so there is no Chromium to install or keep patched.

What you do not need to decide yet

Which AI provider to use, which sources to index, and how many people will use it are all settings you change later from the web interface. Install first.

Installing

tar -xzf proxyma-server-<version>.tar.gz
cd proxyma-server
./install.sh

The first run creates a .env file and stops so you can edit it. Fill it in, then run ./install.sh again.

The installer is idempotent. Re-running it is how you apply a configuration change, and how you upgrade. It never overwrites a value you have already set, never regenerates an existing signing key, and never touches your data.

The one decision

At the top of .env:

COMPOSE_PROFILES=postgres,tls

Proxyma can bring its own PostgreSQL and its own TLS termination, or use yours. A host that already runs those must not get a second copy, so both are opt-in:

An empty value is a normal, supported configuration - it means Proxyma runs as a single container and integrates with what you already have.

Using your own PostgreSQL

Point PROXYMA_DB_URL at it. It can be anywhere the container can reach: another host, a managed service, a container of your own.

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

Proxyma stores embeddings in pgvector, so create the database with the 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 one port on the loopback interface, 127.0.0.1:4246 by default, and your proxy forwards to it. The container serves the web interface and the API on that single port.

Three settings matter. The first two are not optional.

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 no extra configuration.

Also set PUBLIC_ORIGIN in .env to the URL people will type. Proxyma uses it for cross-origin rules and single sign-on redirects.

First start

Open the URL. Proxyma asks you to create the first administrator account. There is no default password and no account exists until you create one.

From there, the recommended order is:

1. Configure an AI provider - Settings, then Providers. Nothing works until one is reachable.
2. Add a source - Resources, then Add Resource. Start with one small folder or project so you can see the indexing pipeline work end to end.
3. Ask a question - the chat page. If the answer cites your document, the installation is complete.
4. Invite people - Administration, then Users.

Choosing an AI provider

Settings → Providers. Proxyma needs two kinds of model, and they do not have to come from the same provider:

Local models

Point Proxyma at an Ollama instance and no document text leaves your network. This is the configuration to pick if your document set is confidential and that matters more than answer quality.

Hosted models

Anthropic, OpenAI, DeepSeek, Mistral, Azure OpenAI and Google are supported. Answer quality is generally better; in exchange, the passages retrieved for each question are sent to that provider's API. Whether that is acceptable is a decision for whoever owns the documents, not one Proxyma can make for you.

Connecting sources

Resources → Add Resource. Each source is indexed on a schedule you set, and Proxyma tracks each document's state individually, so a re-sync only processes what actually changed.

Credentials are encrypted before storage, using the operating system keyring where one is available and an encrypted file otherwise. They are never written to logs, and a credential shown back to you in the interface is always masked.

Watching an index run

Each document moves through DETECTED → QUEUED → DOWNLOADING → CONVERTING → EMBEDDING → COMPLETED. Documents that fail land on FAILED with the reason attached, and one failure never stops the run.

Users and permissions

Data is isolated per user at every storage layer: conversations, uploaded files and their derived indexes. An administrator managing another user's account does not thereby gain access to that user's chat history.

Single sign-on

Google, GitHub and Microsoft are supported alongside email and password. Set the client ID and secret in .env and re-run ./install.sh. Email and password continues to work whether or not single sign-on is configured.

Using Proxyma

Chat

Ask in plain language. Proxyma retrieves relevant passages first, then answers from them, and cites what it used. If nothing relevant is indexed it will say so rather than inventing an answer - that is the intended behaviour, not a failure.

Answers stream as they are produced. If yours arrive all at once at the end, your reverse proxy is buffering - see Troubleshooting.

Search

Proxyma combines keyword matching (BM25) with semantic similarity, fuses the two rankings, then reranks the result. In practice this means both an exact error code and a vague description of a problem find the right document.

The API and MCP

Everything the interface does is available over a REST API. Proxyma also speaks the Model Context Protocol, so editors and agents that support MCP can search your indexed documents directly. The Docs page inside Proxyma has the endpoint reference and a ready-made MCP client configuration for your deployment.

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 manages continuous archiving with pgBackRest for you. Against your own PostgreSQL it cannot - it has no access to your data directory - and takes pg_dump snapshots instead. Your own backup arrangements remain the ones that matter.

Upgrading

Replace the package directory, keeping .env, keys/ and data/, then run ./install.sh. Schema migrations run automatically on start. Take a database backup first.

Troubleshooting

It does not answer on its port

docker compose logs proxyma-server. Nearly always the database: an unreachable host, a wrong password, or pgvector missing.

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

Your reverse proxy is not sending X-Forwarded-Proto. Proxyma builds the redirect URL from that header, and without it builds an http:// one that the provider rejects. It looks like a provider misconfiguration and is not.

Chat answers appear all at once, or seem to hang

Your reverse proxy is buffering the response. Answers stream over Server-Sent Events; with buffering on, nothing appears until the whole answer is finished. proxy_buffering off in nginx.

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

Only relevant with the bundled tls profile. The hostname must resolve to this host from the public internet, with ports 80 and 443 reachable. Behind Cloudflare, set SSL/TLS mode to Full (strict); 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 wants 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 that indexing actually completed - Resources shows per-document status. If you changed the embedding model after indexing, everything must be reindexed before results mean anything.

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 once you are sure.

Getting help

Include the output of docker compose logs --tail 200 proxyma-server, your COMPOSE_PROFILES value, and whether you are using your own PostgreSQL or reverse proxy. Those three answer most questions before they are asked.