Proxyma Home Server

The single-user app for a machine with no screen - a home server, a NAS, a small VPS - reachable from the rest of your network.

This is the desktop app, packaged differently

Same application as the Windows installer and the Linux package: one person, no accounts, no sign-in. AI providers, connectors and licensing work as the desktop manual describes. This page covers installing, who can reach it, and adding documents, which works differently here.

Which package you want

You want to	Install
Use Proxyma on the computer in front of you	Desktop - Windows installer or Linux package
Run it on a headless box and use it from your laptop	This page
Give several people accounts of their own	Proxyma Enterprise Server - a different product, licensed with us directly

Both server packages run in a container. Home Server is for one person: no database to run, no accounts and no sign-in.

Requirements

Component	Requirement
Docker Engine	24 or newer, with the `docker compose` plugin
Memory	4 GB for the container
Disk	20 GB plus whatever your indexed documents need
CPU	2 cores minimum

Nothing else is needed: Java, Python, OCR and the vector store are in the image. Everything the installation keeps is in one directory beside the compose file.

Office Files (the office profile, on by default) adds a small container built on the host, which needs internet once. Remove office from COMPOSE_PROFILES on a host without it.

Installing

Run these on the machine that will host Proxyma, not on your laptop:

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

The first run writes .env and stops.
Set who can reach it in .env (next section).
Run ./install.sh again.
Open Proxyma in a browser. There is no account to create and no password to set.

To apply any later configuration change, run ./install.sh again.

Who can reach it

There is no sign-in, because there are no accounts

Whoever can reach this port has every document you index, every conversation, and your AI provider spend.

Two settings in .env decide it, and both have to agree:

Setting	What it does
`BIND_ADDR`	Publishes the port. `0.0.0.0` puts it on your network; `127.0.0.1` keeps it on the machine.
`PROXYMA_ALLOWED_HOSTS`	The host names Proxyma will answer to. Empty means loopback only, and is the default.

PROXYMA_ALLOWED_HOSTS=homeserver.lan
PROXYMA_ALLOWED_HOSTS=homeserver.lan,192.168.1.50
PROXYMA_ALLOWED_HOSTS=*

Publishing the port without naming your host returns 403 on every request. install.sh prints both settings on every run.

The list is not a firewall: it blocks DNS rebinding from web pages open in your browser. * turns that check off - use it only when something in front of Proxyma decides who gets through.

Reaching it from outside your home

A tunnel (recommended) - Tailscale, WireGuard, or ssh -L 4246:localhost:4246. Through ssh -L, nothing in .env changes. For Tailscale or WireGuard, add the name or address you type to PROXYMA_ALLOWED_HOSTS.
A reverse proxy on the public internet. Set PROXYMA_ALLOWED_HOSTS to your domain. The proxy must require its own login - Proxyma has none, so without it your documents are public.

Two things that switch off when it is exposed

Both are unrestricted on loopback and stay off once the instance answers to any other host. Neither is needed to use Proxyma from a browser.

Setting	What turning it on opens
`PROXYMA_EXPOSE_LOCAL_FILE_API`	On this package, only the endpoint that stops Proxyma. The directory browser it guards on the desktop app is not built in, and documents are uploaded here.
`PROXYMA_EXPOSE_MCP`	The MCP endpoint, unauthenticated: an AI client gets the agent's tools, including those that write to Jira, Confluence and Bitbucket with your stored credentials when your license includes those connectors.

Adding documents

There is no folder picker. You upload documents and Proxyma keeps its own copy.

Open Proxyma in a browser and go to Sources.
Choose Connect, then Upload Files.
Drag in a file or a whole folder.

Uploads are stored and indexed under ./data/uploads, and backed up with ./data.

Deleting a source keeps its files

Removing a source removes it from the index. The uploaded files stay in data/uploads until you delete them.

Day-to-day

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

Backups

./data is the whole installation - database, search index, vector store, conversations and settings.

Stop the container.
Copy ./data.
Start it again.

To copy only your settings to another installation, use Settings → Import & Export.

Upgrading

docker compose pull proxyma
./install.sh

If you pinned a version in PROXYMA_IMAGE, change it to the new version first.

Checking the image is ours

Every release image is signed. With cosign installed:

cosign verify --key https://proxyma.ai/keys/cosign-release.pub ghcr.io/proxyma-ai/proxyma-homeserver:<version>

Troubleshooting

Every request returns 403

The host you typed is not in PROXYMA_ALLOWED_HOSTS. homeserver, homeserver.lan and the IP address are different names.

It answers on the machine but not from elsewhere

Either BIND_ADDR is 127.0.0.1, or the host firewall blocks the port. docker compose ps shows what is published.

Search returns nothing, and the log mentions ChromaDB

The vector store did not start. Run docker compose logs proxyma | grep -i chroma and check ./data/.local/share/proxyma/logs/chromadb.log. Indexing appears to succeed while this is broken, but nothing can be found.

The first start takes over a minute

Expected. The vector store starts before the web port opens.