User manual

Installing, setting up and running Proxyma: search and an AI agent over your own documents and systems, on your own machine or server.

Community and Enterprise

• Search, chat, the agent, guardrails, the knowledge graph, MCP and the HTTP API are in both.
• You bring the AI model. A local model costs nothing beyond your hardware; a hosted provider bills you directly.

Install

Desktop on Windows Community

1. Download proxyma-x64-v<version>.exe from the download page.
2. Run it. It shows the license (GNU AGPL v3); choose Next.
3. Start Proxyma from the Start menu while online. The first start downloads the rest of Proxyma, about 650 MB, then sets up its Python environment (about a minute).
4. Proxyma opens in its own window. Later starts need no internet.

• An interrupted download continues on the next start.
• Every file is checked against the release's signed checksums before it is installed.
• Behind a company proxy, Proxyma uses the Windows proxy settings or HTTPS_PROXY, and the certificate authorities Windows trusts.
• If SmartScreen warns on first run, check the file came from the download page, then choose More info → Run anyway.

Closing the window does not quit Proxyma; it keeps running in the system tray.

• Reopen: double-click the tray icon, or right-click it and choose Open Proxyma. Open in Browser opens it in a browser tab.
• Quit: the menu at the top right, or the tray icon's menu, → Quit Proxyma.
• No icon? Click the ^ next to the clock.

Proxyma listens on 127.0.0.1:4246 only. A browser you open at that address yourself asks for the access code, which is in %LOCALAPPDATA%\proxyma\access-code. The window and the tray sign in for you.

Desktop on Ubuntu and Debian Community

Needs Ubuntu or Debian, 64-bit (x86-64), with an X11 or Wayland desktop session, and the same memory and disk as Windows. For a machine with no screen, use Home Server.

From the Proxyma APT repository (recommended):

sudo install -d -m 0755 /etc/apt/keyrings
sudo wget -qO /etc/apt/keyrings/proxyma.asc https://proxyma.ai/keys/proxyma-release.asc
echo "deb [signed-by=/etc/apt/keyrings/proxyma.asc] https://github.com/proxyma-ai/proxyma-releases/releases/download/apt/ ./" | sudo tee /etc/apt/sources.list.d/proxyma.list
sudo apt update && sudo apt install proxyma

• The key's fingerprint is BE3A B092 AB25 4FA4 5C57 8AF4 F571 F889 94F6 B817.
• From a downloaded file: sudo apt install ./proxyma_<version>_amd64.deb (keep the ./).
• Start Proxyma from the applications menu while online. The first start downloads the rest of the application and sets up Python, as on Windows.
• Starting it again while it runs brings its window back.
• Quit: the menu at the top right → Quit Proxyma. Closing the window does not quit. GNOME without an extension and plain Wayland sessions show no tray icon.
• Run proxyma in a terminal to see its startup messages; closing that terminal stops it.
• The access code is in ~/.local/share/proxyma/access-code.

Home Server on Docker Community

The single-user app in a container, for a home server, a NAS or a small VPS, used from a browser elsewhere on your network.

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

1. The first run writes .env and stops. Set who can reach it (below).
2. Run ./install.sh again. It starts Proxyma and prints the access code.
3. Open Proxyma in a browser and enter the access code.

• Run ./install.sh again after any change to .env.
• The code is printed at every start and kept in ./data/.local/share/proxyma/access-code. To choose your own, set PROXYMA_ACCESS_CODE (at least 16 characters); the log then names that setting instead of printing a code.
• The office profile (on by default) lets the agent create and edit Office files. Its container is built on the host and needs internet once; remove office from COMPOSE_PROFILES on a host without it.
• Without the install script: docker compose -f compose.community.yaml up -d, then read the code with docker compose -f compose.community.yaml logs proxyma | grep -A1 -i "access code".

Who can reach it

• Anyone with the access code has every document you index, every conversation and your AI spend. Share it like a password.
• From outside your home, use a tunnel (Tailscale, WireGuard, or ssh -L 4246:localhost:4246), and add the name you type to PROXYMA_ALLOWED_HOSTS (not needed for ssh -L).
• Behind a public reverse proxy, set PROXYMA_ALLOWED_HOSTS to your domain. * answers any host name; use it only when something in front of Proxyma decides who gets through.

Enterprise Server on Docker Compose Enterprise

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 writes .env and stops. Set at least COMPOSE_PROFILES, PUBLIC_ORIGIN and, with the tls profile, PROXYMA_HOST.
2. Run ./install.sh again. It makes the session signing keys in keys/, a database password for the bundled database, pulls the image, starts the stack and waits until Proxyma answers.
3. Open /setup and create the first administrator with the setup token from the log: docker compose logs proxyma-server | grep "setup token". A restart before setup prints a new one.

• Always start with ./install.sh: without its keys the server stops with Failed to load JWT keys. It never overwrites a value you set, never makes new keys and never deletes data.
• To pin a version, set PROXYMA_IMAGE=ghcr.io/proxyma-ai/proxyma-enterprise-server:<version>.
• Image only, with no install script: compose.enterprise.yaml in the bundle (Docker Compose 2.20.2 or newer). Put PROXYMA_DB_PASSWORD=... in .env, run docker compose -f compose.enterprise.yaml up -d, and read the setup token from its log. Its bundled database has no continuous backups.

The shipped value is postgres,tls,office. Leave out what your host already has. With none, Proxyma runs as one container.

Your own PostgreSQL

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

• Set PROXYMA_DB_URL, PROXYMA_DB_USER and PROXYMA_DB_PASSWORD, and leave postgres out of COMPOSE_PROFILES.
• If CREATE EXTENSION fails, pgvector is not installed on that server. Managed services (Amazon RDS, Google Cloud SQL, Azure Database) enable it per instance.
• Proxyma creates its own tables on start.

Your own reverse proxy

Leave tls out of COMPOSE_PROFILES and forward to 127.0.0.1:4246. The proxy must pass Host, X-Forwarded-For and X-Forwarded-Proto, must not buffer responses (answers stream), and needs a long read timeout. nginx:

location / {
    proxy_pass http://127.0.0.1:4246;
    proxy_http_version 1.1;
    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;
    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 forwards the headers and does not buffer by default; it needs only the router and loadbalancer.server.port=4246.

Without registry access

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
# on the server:
docker load < proxyma-enterprise-server.tar.gz

Set PROXYMA_IMAGE to that tag and run ./install.sh. The postgres, tls and office profiles pull images of their own, so a host with no registry uses COMPOSE_PROFILES= with its own database and proxy.

On Kubernetes

Two Helm charts, attached to every release: proxyma-enterprise-<version>.tgz Enterprise and proxyma-community-<version>.tgz (Home Server) Community, each also as plain manifests (proxyma-<edition>-<version>.yaml). They need Kubernetes 1.27 or newer.

helm install proxyma-enterprise https://github.com/proxyma-ai/proxyma-releases/releases/download/v<version>/proxyma-enterprise-<version>.tgz -n proxyma --create-namespace
kubectl -n proxyma logs statefulset/proxyma-enterprise | grep -i "setup token"
kubectl -n proxyma port-forward svc/proxyma-enterprise 4246:4246

Then open http://localhost:4246/setup. For Community, use proxyma-community and read the access code with kubectl -n proxyma logs statefulset/proxyma-community | grep -A1 -i "access code".

• One replica. An upgrade means a minute or two of downtime.
• Block storage only (ReadWriteOnce); not NFS, EFS, SMB or Azure Files. persistence.size is 20Gi by default.
• Pin the image with image.digest or image.tag.
• Address: set config.publicUrl and turn on ingress. The nginx preset turns off buffering and allows 200 MB uploads.
• Database: postgresql.enabled runs PostgreSQL 16 with pgvector (no continuous backups); or set externalDatabase.*.
• Secrets: secrets.existingSecret holds credential-key, setup-token, license-activation-key, sandbox-token and db-password (Community: access-code, credential-key, sandbox-token). Use it with Argo CD or Flux.
• Trial: license.trialEnabled (on by default); license.clusterId defaults to the kube-system namespace's uid.
• Single sign-on: pass its variables (see Single sign-on) through config.extraEnv.
• Probes: /api/v1/health/live and /api/v1/health/ready.
• Plain manifests: kubectl apply -n <namespace> -f proxyma-community-<version>.yaml. Enterprise first needs its database Secret: kubectl -n <namespace> create secret generic proxyma-postgresql --from-literal=password="$(openssl rand -hex 24)".
• Upgrade by rolling forward to the new chart version; helm rollback cannot undo a database change.
• Back up the data volume, the database and the credential-key Secret.

Enterprise trial and license Enterprise

• The trial starts by itself. On its first start, an Enterprise Server with internet asks the Proxyma license server for a 30-day trial of every Enterprise feature. No card and no form.
• Once per deployment. Reinstalling within the 30 days gets the same trial back; after that, the deployment has used its trial.
• What it sends: a random deployment identifier, and one-way hashes of the host's machine id and of the cluster id. Nothing about your documents or people.
• Before the trial starts (or without a license), the server has one account, the first administrator, and no Microsoft 365.
• Settings → License (Super admin) shows the plan, the days left, and the deployment code.

A server with no internet

1. Set PROXYMA_LICENSE_TRIAL_ENABLED=false (Helm: license.trialEnabled: false).
2. In Settings → License, choose Copy deployment code.
3. On any connected machine, open proxyma.ai/enterprise/trial, paste the code and choose Get a trial key.
4. Back on the server, choose Activate license, paste the key and choose Activate. It is checked on the server, with no network call, and works on that deployment only.

A license

• Buy one on the pricing page; the license key arrives by email. For a quote, write to contact@proxyma.ai.
• Activate it in Settings → License → Activate license. A license key is activated online, once; a signed license issued for your deployment code is checked offline.
• Proxyma confirms the license every few hours. If the license server cannot be reached, nothing changes; a banner appears after a while.
• Release this license frees it for another deployment.

When the trial or license ends

The server keeps working and stops growing:

• Everyone keeps signing in, by password and by single sign-on. Search, chat and every source keep running.
• New accounts wait for a license.
• Microsoft 365 sources stay listed and searchable, and stop syncing.
• Key accounts become read-only, and the agent's key-account tools are not offered.
• Spending limits stay in force, and the logs keep recording.
• Everyone sees a banner in the last 7 days of a trial.

First run

1. Add an AI provider in Settings → AI Providers. Nothing works until one is reachable. The page lists what is still to choose.
2. Choose the models: the chat model in Settings → Agents, the embedding model in Settings → Search.
3. Add a source in Sources → Connect. Start small.
4. Ask a question. An answer that cites your document means setup is complete.

Enterprise The AI provider and model settings are an administrator's; a Super admin changes them. Then add people in Administration → Users, or let them sign in with single sign-on.

AI providers

• Protocols: OpenAI, Anthropic, Google Gemini, Azure OpenAI, Ollama, OpenRouter, LiteLLM, and OpenAI-compatible for any server that speaks OpenAI's API (DeepSeek, Mistral, Groq, Together, vLLM, LM Studio are offered as starting points).
• Fully local: install Ollama and use http://127.0.0.1:11434. No document text reaches a provider. Expect slower, weaker answers than hosted models.
• Hosted: your questions and the passages the agent reads go to that provider, under your account and its terms. For confidential documents, use a local model.
• Changing the embedding model means reindexing everything before search is reliable again.
• A company AI service with its own certificate: see Troubleshooting.

What it costs

• Costs are estimated from the rates you set on each provider, not read from your provider's bill. A model with no rate counts as $0 and is marked.
• Logs → LLM calls lists every model call with its tokens and cost.
• Community The monthly spending limit is in Settings → Usage & Cost.
• Enterprise Administration → Usage & cost shows cost by service, provider, model and person. Limits are in Spending limits.

Sources

A source is something Proxyma indexes: a folder, a website, a Jira project, a Slack channel. Most sources read through a connection: the address and credentials of one account on one service.

1. Add the connection in Settings → Connections → Add connection, and choose Test.
2. Add the source in Sources → Connect, choose the connection, and fill in what to read.

• Add one connection per server or account. The first of each kind is the default; a source's Configure dialog moves it to another.
• Proxyma reads, and never changes anything at the source. Only Jira, Confluence and Bitbucket (Data Center or Server) connections can be given Write, for the agent (see The agent).
• Stored credentials are encrypted.
• Enterprise Connections are each person's own. A source is private to whoever added it until they share it; sharing lets colleagues search what it indexed. Some types can never be shared (below), because they were read with one person's access.
• Enterprise Where a service signs in with OAuth, an administrator sets up the app once for everyone, and people only sign in.

Every source type

Where a connection can sign in with OAuth, register an app at the service, set its redirect address to the one the connection dialog shows (the address you open Proxyma at, followed by /api/v1/connections/oauth/callback), paste its client ID and secret into the connection, save, and choose Sign in. Ask for read access only.

Files

• Community Desktop: Local folder, then choose a folder. It is indexed where it is, never copied or changed. Include subfolders is off until you turn it on.
• Home Server and Enterprise Server: Upload files, then drag in files or a whole folder, up to 200 MB a file. Proxyma keeps its own copy, and deleting the source deletes that copy.
• Choose the file types to index when you add the source, or later in Configure.

Web pages

• Give a Starting URL and a name.
• Crawl depth: 3 links deep by default, up to 50. Max pages: 100 by default, up to 20,000.
• Stay on the same domain is on by default. Render JavaScript reads pages built in the browser.
• To narrow the crawl, open the source's Configure and set Only follow URLs matching.

Network shares

1. Add a Network share connection: the file server, and your domain user name and password.
2. In Sources → Connect, choose Network shares and give the path, such as \\fileserver\share\folder.

• Files are read as your account, so only what you can open is indexed, and only on that server.
• A password the server rejects is not tried again until you change it.
• Enterprise A Super admin can list the file servers people may use, in Settings → Network → Allowed file servers.

Jira, Confluence and Bitbucket

Jira

• Cloud: create an API token at id.atlassian.com (Security → API tokens). In the connection choose Email and API token (Cloud) and enter https://your-site.atlassian.net, your email and the token. One token works for Jira and Confluence; it expires on the date you chose.
• Data Center or Server: create a personal access token in your Jira profile, and enter the server address (with its path) and the token.
• Source: the project key, PROJ in PROJ-123. Each issue is one document: its fields, description, links, subtasks, comments and change history.

Confluence

• The connection works as for Jira. On Data Center or Server, create the personal access token under your profile picture → Settings → Personal Access Tokens.
• Source: the space key, TEAM in /spaces/TEAM/ or /display/TEAM/. Each current page is one document, with its labels, place in the page tree, authors and comments. Blog posts and attachments are not indexed.

Bitbucket (Data Center or Server)

• Create an HTTP access token in Bitbucket, and enter the server address and the token.
• Source: the project key and the repository slug.

Bitbucket Cloud

• Email and API token: at id.atlassian.com choose Create API token with scopes, app Bitbucket, with read:repository:bitbucket, read:pullrequest:bitbucket and read:user:bitbucket.
• Access token: a workspace, project or repository access token with Repositories: Read and Pull requests: Read.
• Source: workspace/repository. Pull requests are on by default; Documentation files (Markdown and text files up to 1 MB on the main branch) are off. Code is not indexed.

Jira, Confluence and Bitbucket sync every hour, reading only what changed, and remove deleted items once a day.

GitHub, GitLab and SVN

GitHub

• Create a classic token with the repo scope, or a fine-grained token that can read issues, pull requests and contents. For GitHub Enterprise Server, set API URL to https://your-host/api/v3.
• Source: owner/repository. Issues and Pull requests are on; Documentation files on the default branch are off. Code is not indexed. Syncs every hour.

GitLab

• Create a personal, group or project access token with the read_api scope only (group and project tokens with the Reporter role). For a self-managed GitLab, set GitLab URL.
• Or sign in with OAuth on gitlab.com: an application with the read_api scope, marked Confidential.
• Source: a project path (acme/website) or a group (acme, with its subgroups). Issues and merge requests are on; documentation files are off. Code is not indexed.

SVN

• The connection takes the repository root URL, your user name and your password. On a VisualSVN server with Windows authentication, the user name is domain-qualified.
• Source: the repository path. Choose the file types; Include subfolders is on by default.

Work tracking

Linear

• Create a personal API key with Read access in Settings → Security & access, or sign in with an OAuth application.
• Source: team keys such as ENG, OPS; empty reads every team.

Asana

• Create a personal access token in the developer console (My apps), or sign in with an app that has the read scopes workspaces:read, projects:read, project_sections:read, tasks:read, stories:read, users:read, custom_fields:read and tags:read.
• Source: the workspace, and project IDs or names; empty reads every project you can see.

monday.com

• Copy your personal API token (profile picture → Developers → API token), or sign in with an app that has me:read, account:read, boards:read, updates:read and users:read.
• Source: board IDs or links; empty reads every board you can see. Syncs every two hours. Free, Basic and Standard plans allow 1,000 API calls a day; the sync continues after midnight UTC.

Trello

• Create a Power-Up at trello.com/power-ups/admin, generate its API key, and follow the Token link beside it to get a token. Paste both.
• Source: board links or IDs; empty reads every open board you belong to.

ClickUp

• Generate a personal API token (pk_...) in Settings → Apps, or sign in with a ClickUp app.
• Source: the workspace, and optionally space, folder and list IDs.

Airtable

• Create a token at airtable.com/create/tokens with data.records:read and schema.bases:read (and user.email:read for Test), with access to each base. Or sign in with an OAuth integration with the same scopes.
• Source: the base (ID or link), and optionally a table and a view. Attachments are listed by name; their contents are not indexed.

Notion and Slack

Notion

1. At notion.so/profile/integrations, create an Internal integration with Read content only, and copy its secret (ntn_...).
2. In Notion, share each page or database with it (... → Connections). Sharing a page shares the pages under it.
3. Source: page or database links, one per line; empty reads everything shared with the integration.

Slack

1. At api.slack.com/apps, choose Create New App → From a manifest, with these bot scopes: channels:history, channels:read, groups:history, groups:read, users:read. There is no scope for direct messages.
2. Install to Workspace, copy the Bot User OAuth Token (xoxb-...), and paste it into the connection.
3. Invite the app to each channel: /invite @Proxyma.
4. Source: channels as #name or IDs (empty: every public channel the app is in), and how many days back.

• Sign in with Slack works too, on an https:// address only.
• Each thread is one document; messages outside threads are one document per channel per day.
• Check Slack's API terms and your workspace's policies before indexing.

Google: Drive, Gmail and Calendar

One Google connection serves all three, with read-only access. You need a Google Cloud project with the Drive, Gmail and Calendar APIs enabled (only those you use).

• Sign in with Google: configure the OAuth consent screen (Internal for a Workspace organization, otherwise External) with the scopes drive.readonly, gmail.readonly and calendar.readonly. Create an OAuth client ID of type Web application with the redirect address from the dialog, and paste its ID and secret. An External app in Testing must sign in again every 7 days.
• Service account (Google Workspace): create a service account with a JSON key, give its client ID domain-wide delegation with the same three scopes in the Admin console, then paste the JSON key and the user to act as. One connection reads as one user.

Google Drive

Choose My Drive, Shared with me, shared drives, or one folder. Docs are read as Markdown, Sheets as CSV (first sheet), Slides as text. Google exports at most 10 MB of a Doc, Sheet or Slides; other files over 100 MB are skipped.

Gmail

Choose the labels (INBOX by default) and the days of mail (365). One conversation is one document; attachments are listed by name. Drafts, spam and trash are never read.

Google Calendar

Choose the calendars (primary by default), the days back (365) and ahead (180). Each event, and each occurrence of a repeating one, is one document.

IMAP, Dropbox and Box

IMAP mailbox

• Most mail services want an app password: Gmail (imap.gmail.com), iCloud (imap.mail.me.com), Yahoo (imap.mail.yahoo.com), Zoho (imap.zoho.com). Outlook.com and Microsoft 365 mailboxes do not accept passwords over IMAP.
• The connection: the mail server, Security (TLS on port 993, or STARTTLS on 143), your user name and the password.
• Source: folders, one per line; optionally a Received since date and Only these domains. Attachments are indexed as documents of their own unless you turn them off. Folders are opened read-only.

Dropbox

• At dropbox.com/developers/apps, create a Scoped access, Full Dropbox app with files.metadata.read and files.content.read, add the redirect address, and copy the app key and secret. An access token works for a quick try and expires after four hours.
• Source: a folder path or link; empty reads your whole Dropbox. Paper docs count as Markdown in the file types. Files up to 100 MB.

Box

• In the Box Developer Console, create a Platform App with User Authentication (OAuth 2.0), add the redirect address, keep only Read all files and folders stored in Box, and copy the client ID and secret. A developer token works for 60 minutes.
• Or Client credentials (server app): a Platform App with Server Authentication (Client Credentials Grant) that your Box admin authorized. It reads as the app's service account (your enterprise ID) or as one user (their user ID).
• The sign-in lasts while Proxyma syncs at least once every 60 days.
• Source: a folder ID or link; empty reads All Files. Files up to 100 MB.

CRM and support

HubSpot

• Create a Service Key (Settings → Integrations → Service Keys) with crm.objects.companies.read, crm.objects.contacts.read, crm.objects.deals.read, tickets and, to name owners, crm.objects.owners.read. A legacy private app token works too, or sign in with a HubSpot app.
• Source: the records to index; companies, deals and tickets by default.
• The connection reads the whole account, whatever a given user may see in HubSpot.

Salesforce

• Create an External Client App with OAuth scopes api, id, profile, email, address, phone and refresh_token, offline_access.
• Sign in with Salesforce (production orgs): set the callback to the address in the dialog and require PKCE. Or JWT bearer for an integration user: upload a certificate to the app and paste the consumer key, the user name and the private key.
• Set My Domain URL, such as https://acme.my.salesforce.com.
• Source: the objects; accounts, opportunities and cases by default. Custom fields are not read.

Zendesk

• In Admin Center → Apps and integrations → APIs → Zendesk API, turn on Token access and add a token. The connection takes the subdomain, an agent's email and the token, and reads what that agent can see. Or sign in with an OAuth client.
• Source: Tickets (on), Internal notes (off), Help Center articles (off), article languages and sections.

Freshdesk

• Copy your API key from Profile settings → View API key. The connection takes the domain and the key, and reads what that agent can see.
• Source: Tickets (on), Private notes (off), Knowledge base articles (off), article categories.

Zoom

Zoom

• Server-to-Server OAuth app (an account administrator, at marketplace.zoom.us): add the scopes user:read:user:admin, user:read:list_users:admin, cloud_recording:read:list_user_recordings:admin, cloud_recording:read:list_recording_files:admin, meeting:read:list_summaries:admin, meeting:read:summary:admin and meeting:read:list_past_participants:admin, activate it, and paste the account ID, client ID and secret.
• Or Sign in with Zoom through a General App with the same scopes without :admin.
• Source: people's email addresses (empty: yourself; *: everyone, with a Server-to-Server app) and days of meetings (365).
• Transcripts need cloud recording with audio transcripts on; summaries need AI Companion meeting summaries.
• Transcripts hold what people said. Index only meetings whose participants would expect it.

Microsoft 365 Enterprise

OneDrive, SharePoint, Teams and Outlook, read with each person's own Microsoft account. Microsoft 365 sources cannot be shared.

1. A Microsoft 365 administrator registers a single-tenant app in Microsoft Entra ID, with the Web redirect URI https://<your server>/api/v1/microsoft/oauth/callback and a client secret, and these delegated Microsoft Graph permissions:
   • Every source: openid, profile, email, offline_access
   • OneDrive and SharePoint: Files.Read.All, Sites.Read.All
   • Outlook: Mail.Read, Mail.Read.Shared, Calendars.Read, Calendars.Read.Shared
   • Teams channels: Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMessage.Read.All (admin consent)
   • Teams chats: Chat.Read
2. A Super admin enters the tenant ID, client ID and client secret in Settings → Network → Microsoft 365, and turns on the sources the organization allows: Teams channels, Teams chats, Outlook. OneDrive and SharePoint need no switch.
3. Each person adds a Microsoft 365 connection in Settings → Connections and chooses Sign in. Anyone who signed in before a switch was turned on signs in again.

OneDrive

Your whole OneDrive, or one folder by its path, such as Documents/Reports, with everything inside it. OneNote notebooks are skipped.

SharePoint

Paste the site's address and give it a name. The site's pages and the files of every document library are indexed.

Teams channels

One channel of a team you have joined, by team and channel name. Each message is one document, with its replies.

Teams chats

Your own one-to-one and group chats, one document per chat per day (UTC). Choose how many days back; 0 reads all.

Outlook

One mail folder (with its subfolders if you choose) or one calendar, from your mailbox or a shared one you can open. A calendar covers 365 days back and ahead; a Super admin sets the window in Settings → Network.

Custom sources

• A custom source holds documents that your scripts and tools (Zapier, Make, n8n, a cron job) push to it. Nothing is pulled.
• Add one in Sources → Connect → Custom source, open it, and choose Ingestion API for its endpoint and Create token. The token is shown once.
• A token opens that one source's ingestion endpoints and nothing else. Revoke it on the same panel.
• The assistant can save a note into a custom source you own; like any write, it asks first in Ask mode.
• The calls, fields and limits are in the API reference.
• Enterprise Only the source's owner pushes to it and creates its tokens. Sharing it lets others search it.

Formats and OCR

• PDF; Word, Excel and PowerPoint (.docx, .xlsx, .xls, .pptx and their macro-enabled versions); Outlook .msg; EPUB; CSV, Markdown, plain text and HTML; C and C++ source; shell, batch and PowerShell scripts; AUTOSAR and embedded files (.arxml, .dbc, .a2l, linker scripts, assembly).
• Save older .doc and .ppt files as .docx and .pptx first.
• Tables in PDFs are kept as tables.
• Scanned PDFs need OCR: choose an OCR model in Settings → Conversion, or the Tesseract engine. Tesseract comes with Proxyma and reads English and Vietnamese (set Tesseract languages to eng+vie for both). On Linux, if your system skips recommended packages: sudo apt install tesseract-ocr tesseract-ocr-eng tesseract-ocr-vie.

Sync and status

• Each document goes through detection, download, conversion and embedding. A failed document shows its reason and does not stop the rest.
• A sync processes only what changed. Most services sync every hour; Gmail and IMAP every 30 minutes, monday.com every 2 hours, network shares every 6 hours and websites once a day.
• Sync now runs a full sync, which also removes what was deleted at the source.
• After changing the embedding model, open each source and choose Re-index.
• When a service limits how often it is asked, the sync waits, or stops and continues next time. Nothing is lost.

Using Proxyma

• Ask in plain language. Proxyma answers from the passages it finds and cites them. With nothing relevant indexed, it says so.
• Search matches keywords and meaning together, so an exact error code and a vague description both work.
• Mention a source to search it first, or a skill to load it for one message.
• Attach a file to a message for the agent to read.

Conversations

• Conversations are kept where Proxyma runs. A hosted AI provider receives the conversation to answer it.
• An idle conversation is deleted after 7 days unless you pin it. Change this in Settings → Data Retention → Conversations (days); 0 keeps them.
• Enterprise Each person's conversations are their own. Managing someone's account does not open their conversations.

The knowledge graph

Proxyma can extract the things documents mention - components, services, people - and how they relate, into a graph. The agent uses it to answer how things connect, who works on what, and what happened when, and quotes the passage behind each relationship.

1. In Settings → Search, turn on Knowledge graph and choose the extraction model. If extraction times out, raise Extraction timeout.
2. In a source's settings, turn on Build a knowledge graph. What is already indexed is extracted in the background; nothing is reindexed.

• Extraction costs one model call per passage. Start with one source.
• Jira, Confluence, Bitbucket and SVN also give relationships their own fields record (assignees, linked issues, page trees, authors, reviewers), with dates. These need no model.
• Knowledge graph in search (Settings → Search, off by default) also ranks search results by the graph.
• To see the graph, open a source and choose the graph icon. Drag to rotate, scroll to zoom, shift-drag to pan, click a point to see its links. Stars sets how many points are drawn.
• Turning the graph off for a source deletes what that source added to it. Its index stays.
• Enterprise A person sees only relationships stated in sources they can read.

Memory

• The agent saves facts and your preferences, and checks them before it searches.
• Settings → Memory lists them under About you and Knowledge: edit, move or delete any entry.
• Enterprise Each person sees only their own.

The agent

The agent searches your sources and can read your systems live. Where you allow it, it changes them: comments on a ticket, moves it, opens a pull request.

The three gates

Every change passes all three.

1. Permission, per connection. Jira, Confluence and Bitbucket (Data Center or Server) connections have Read (on) and Write (off) switches in Settings → Connections. Write off refuses every change at once; it does not undo past ones.
2. The mode, beside the model under the message box. It starts at Ask each time you open Proxyma.
   • Ask: each change waits for Allow once, Allow for this conversation or Deny. Unanswered, it is denied after 5 minutes in the page, or 30 minutes with the page closed.
   • Auto: changes go ahead without asking. Write must still be on.
   • Read-only: every change is refused.
3. Your own credentials. Every action uses your connection, so the agent can do nothing you could not, and a change appears under your name.

What it can reach

• The agent can also call any Jira, Confluence or Bitbucket API endpoint directly. A read needs Read on; anything else needs Write on and, in Ask, your approval.
• Approving or merging a pull request cannot be undone from Proxyma, and an approval counts toward merge checks under your name.
• Office files: the agent creates and edits Word, Excel and PowerPoint files. On Desktop it can save them to your computer, asking first; on the servers it works on attached files in an isolated container.
• Web search uses DuckDuckGo with nothing set up, or Google with a Custom Search key and engine ID in Settings → Search → Web search. It is used even with a local model.

Sub-agents

• The agent hands parts of a task to sub-agents, each with its own context. They run in the background while you keep chatting, and pass the same three gates; in Ask, the prompt names the sub-agent.
• Each has a panel in the conversation with its own Stop. The button beside the model opens the agents window: every agent, its steps, and what it used and cost.
• They use the agent's model unless you choose another in Settings → Agents → Sub-agents. A cheaper model there keeps long reading cheap.
• When the provider's rate limit is reached, agents wait and retry for up to 10 minutes.

How long it works

• An iteration is one model call and the tool calls it makes. At the limit the agent asks: Continue gives it as many again; Stop here has it answer with what it has.
• Other tools stop after one minute. Waiting for your approval is not counted.
• Stop ends a run at any time.
• Prompt cache (Anthropic, OpenRouter, and LiteLLM on Anthropic Messages): Auto keeps the conversation cached for 5 minutes, or 1 hour while sub-agents work or after a longer pause.

MCP servers

The agent can use the tools of other MCP servers.

1. In Settings → Connections → Add connection, choose MCP server.
2. Choose the transport: Streamable HTTP or SSE for a server at an address, or Local command for a program Proxyma starts, such as npx or uvx, with one argument per line.
3. For an address, choose the sign-in: none, a bearer token, custom headers, or OAuth (save, then Sign in).
4. Choose Test; it says how many tools the server offers.

• The agent sees each server as a skill named MCP: and the connection's name.
• Every call to its tools waits for your approval, except in Auto; Read-only refuses them.
• Enterprise Only a Super admin can add a local command, or share a server with everyone.

Checking that everything works

1. In chat, ask: Run a self test.
2. Choose Reads only, or Reads and writes with a test Jira project, Confluence space or Bitbucket repository; what it creates is deleted at the end.
3. Attach a PDF or Word file when asked.
4. Each check reports PASS, FAIL, SKIPPED or NEEDS YOU, with a fix for each failure.

Guardrails

Guardrails check what people send, what the agent reads and what it answers. They are on from the start, need no AI model and send nothing anywhere. Settings are in Settings → Guardrails and apply to the whole installation.

• A blocked message is refused and not stored. A withheld source is left out and the agent carries on. An answer is stored with the match removed, for example [redacted: secret].
• Notices and logs name the rules and categories that fired, never the text that matched.
• Text is normalized first, so invisible characters and lookalike letters do not hide a match.
• The last few hundred characters of an answer appear when it finishes, not word by word.

Watch before you enforce

1. Set Mode to Monitor only: every check runs and nothing is blocked.
2. Read Logs → Guardrails: how many checks ran, what would have been withheld, and which rules fired.
3. When it looks right, set Mode to Enforce.

Your own rules

• Judge meaning with a model (off) sends each message, and with Also check answers each answer, to the Guardrail model you choose. It judges against a built-in list (violence, self-harm, sexual content involving minors, weapons, harassment and hate) and your own rules.
• Rules from your documents: upload policies (Markdown, PDF, Word, Excel or PowerPoint, up to 20 MB each). Only the clauses that bear on a message are sent. Policy documents are never search results.
• With these on, the text judged goes to the guardrail and embedding providers. Use local models to keep it on the machine.
• If the model cannot be reached, the message goes through, unless Refuse when the model cannot be reached is on.
• Detect a leaked system prompt (off) refuses an answer that quotes the agent's instructions; it does not catch a paraphrase.
• Slow down repeated attempts (off) pauses someone refused several times in a row, until restart. Pasting logs with tokens can trip it.
• Keep the matched text (off) keeps what each rule matched, in memory only (200 decisions, 120 characters each), for administrators to read in Logs.

Guardrails are a text filter, not access control. The prompt-injection patterns catch copied attempts, not careful rewording. If the retrieval check itself fails, the source goes through.

MCP and the HTTP API

Claude Code, Claude Desktop, ChatGPT, Gemini CLI, GitHub Copilot, Cursor and your own scripts can search what Proxyma has indexed, over MCP at /mcp and the HTTP API. They see what their token's owner can see. Settings → AI Assistants shows each client's configuration, ready to copy. See the HTTP API and MCP reference.

Keeping it running

Updates

• Community Desktop updates itself: Settings → Updates checks once a day by default (or every 6 hours, once a week, or never), downloads only the parts that changed, verifies them against the release's signed checksums, and waits for Restart and install. A version that fails to start is rolled back by itself. Your data is not touched. Development builds (off) also offers test builds.
• Community Home Server: docker compose pull proxyma, then ./install.sh. With a pinned PROXYMA_IMAGE, change it first.
• Enterprise Back up the database, replace the bundle directory keeping .env, keys/, data/ and any docker-compose.override.yml, then docker compose pull proxyma-server (or change a pinned PROXYMA_IMAGE) and ./install.sh. Name the service: a bare docker compose pull fails on the locally built database image. The schema updates on start.
• Check an image is ours: cosign verify --key https://proxyma.ai/keys/cosign-release.pub ghcr.io/proxyma-ai/proxyma-enterprise-server:<version> (or proxyma-homeserver).

Logs

Community Settings → Logs. Enterprise Administration → Logs, for everyone, with a Who filter.

• Choose a period (7, 30 or 90 days, or 12 months), then search, filter and sort. Open a row for everything recorded with it.
• Download as CSV or JSON: the entries under your filters, up to 10,000.
• Community Clear log deletes a tab's entries, and the clear is recorded. Clearing LLM calls restarts this month's count toward the spending limit.
• Enterprise Nobody can clear tool calls, guardrail checks or activity. A Super admin can clear LLM calls; the deployment's monthly limit then counts from zero. Tool-call inputs and results are shown to a Super admin only.

Data retention

Settings → Data Retention. Swept daily; 0 keeps forever.

Import and export settings

Settings → Import & Export copies configuration to another installation as one JSON file. It is not a backup: conversations, documents and the index are not in it.

• Export: tick the groups (named after the Settings tabs). To include credentials, keep Include credentials, encrypted with a passphrase and enter a passphrase of at least 12 characters; it cannot be recovered.
• Import: enter the passphrase if any, Choose file (then Read this file), untick what you do not want, check the changes, and Import it.
• An import only adds and updates. Names already in use are kept.
• Never exported: the license, appearance, Microsoft 365 sign-ins, API tokens and accounts, and each connection's Read and Write switches (an imported connection starts with Read on and Write off).
• Enterprise Super admin only; it carries their own connections.

Where data lives, and backups

• Your own documents stay where they are; Desktop never copies them.
• Credentials are encrypted with a key kept in the data folder (on Windows, protected by DPAPI for your account). Losing the data folder means reindexing and entering credentials again.
• Enterprise Losing the database is unrecoverable. Restore data/ and the database together, or Proxyma lists documents it cannot read.
• Enterprise The bundled database is backed up continuously with pgBackRest into data/pgbackrest-repo; with your own database Proxyma takes pg_dump snapshots, so keep your own backups too. Restore in Administration → Operations → Backups: Restore, then type the backup's file name. A restore replaces all data, and Proxyma is unavailable until it finishes.

Enterprise administration Enterprise

Users and roles

• Add people in Administration → Users, let them sign in with single sign-on, or set PROXYMA_SELF_REGISTRATION=true.
• Forgotten password: Proxyma sends no email. A Super admin opens the person and chooses Make a password reset link; it works once, within an hour.
• Deleting an account waits 7 days, during which it can be recovered. An account that signs in with single sign-on has its data deleted at once and is kept.

Single sign-on

Email and password keep working beside these. Set the variables in .env and run ./install.sh. Register each redirect address exactly: https, the host people type, no trailing slash.

Single sign-on goes through your reverse proxy's X-Forwarded-Proto; without it the redirect uses http:// and fails.

Spending limits

• Settings → Usage & Cost: the deployment's monthly limit, and each person's default quotas (monthly, 5-hour and weekly). A person sees a marker past 80% of their 5-hour quota.
• Administration → Users, open a person: their own quotas and storage quota.
• Each person sees their usage in Settings → Account.

Sharing sources

• The owner shares a source from the Sources page; everyone can then search it. Sharing is all or nothing.
• Their live actions in that system still need their own connection.

Administration

Admins can open the system settings; only a Super admin can change them.

Key accounts

A shared review of an important client: how healthy the account is, and what to do next. The agent reads the sources you link and proposes facts, ratings and next moves with their evidence; none of them counts until a person confirms it.

1. Key accounts → New account: name, tier, goal, renewal date and ARR. You are its Owner, and its first review opens.
2. Under Sources for the assistant, link the sources that hold its contracts, tickets, minutes and revenue. Linking gives nobody access to a source.
3. Share it, and give each person a role.
4. Open the assistant panel and choose Run the health review. Proposals appear on Profile, Health, People and Opportunities.
5. On Health, rate each question from 1 to 5 and choose Confirm and continue. On Profile, verify each fact.
6. Ask the assistant to Draft next moves, then Accept (with an owner and a due date), Reject or Defer each. Accepted moves become actions on Plan.
7. On Report, draft, Save draft, and the Owner chooses Sign. A signed report cannot be edited.

• The assistant cannot confirm a rating, decide a move, sign, change members, delete, or record how a stakeholder feels. Its other changes follow the panel's mode.
• Overview shows the health score (0-100, from confirmed ratings), ARR, days to renewal, whitespace, sponsor coverage and plan progress. Import revenue takes a CSV with month, actual and optional plan columns.
• Activity lists every change with its before and after. New review carries confirmed ratings and open actions over.
• A Super admin can read every key account, and change only those they are a member of.

Data and privacy

• Your documents are indexed and stored where Proxyma runs.
• What leaves: text sent to the AI providers you choose (to index, to answer, to extract the graph, to judge guardrails); the agent's web searches and the pages it opens; what it asks the systems you connect; and feedback you send.
• Community Settings → About → Privacy → Send diagnostics to Proxyma (off) sends a daily report of error types, timings and features in use, never content. With it on, rating an answer sends that answer and its question, anonymously. Logs → Diagnostics → See what would be sent shows the exact report. Community never contacts the license server.
• Enterprise Enterprise Server never sends diagnostics or rated answers. It contacts the license server for the trial and to confirm the license.
• Absolute server paths are removed from what the agent shows you.
• Enterprise Search, chat, the API and MCP reach only the caller's own sources and shared ones. Administrators read every person's tool calls in the logs.
• Deleting a source removes its index. On Desktop your folder is untouched; uploaded files are deleted with their source.
• Enterprise Deleting an account removes its connections, conversations, settings and uploads after the 7-day wait; files on disk are removed in the background.

The Privacy Policy covers what Proxyma, the company, processes.

Troubleshooting

It will not start

• Community Desktop: check antivirus is not blocking Proxyma's files, including %LOCALAPPDATA%\proxyma\parts\. If the first start stops while downloading, check the machine can reach GitHub and start again.
• Community Linux: run proxyma in a terminal to see the error. If the log mentions the vector database, read ~/.local/share/proxyma/logs/chromadb.log; a leftover process from a killed session is the usual cause. If the Python setup failed, delete runtime/ there and start again.
• Enterprise Run docker compose logs proxyma-server. It is nearly always the database: wrong host, wrong password, or no pgvector.
• Container restarts or runs out of memory: give it 4 GB; with the bundled database, lower PG_SHARED_BUFFERS or move the database.

It asks for an access code, or answers 403 Community

• Home Server prints the access code at every start, unless you set PROXYMA_ACCESS_CODE. Desktop and Home Server keep it in the data folder's access-code file.
• 403 on every request: the host name you typed is not in PROXYMA_ALLOWED_HOSTS. homeserver, homeserver.lan and the IP address are different names.
• Works on the machine but not elsewhere: BIND_ADDR is 127.0.0.1, or a firewall blocks the port.

No AI provider responds, or a certificate error

• Open Settings → AI Providers. For Ollama, check http://127.0.0.1:11434 answers in a browser.
• PKIX path building failed: the service uses a company certificate authority. Desktop trusts what your operating system trusts, so have IT install the root certificate. Enterprise A Super admin pastes it in PEM form under Settings → Network → Custom CA certificate.

Search finds nothing, or the wrong thing

• Check in Sources that indexing finished, and look at failed documents.
• After changing the embedding model, reindex.
• Scanned documents depend on OCR quality.
• Community Home Server: if the log mentions ChromaDB, read ./data/.local/share/proxyma/logs/chromadb.log. Indexing seems to succeed while the vector store is down.
• Answers are only as good as what is indexed and the chat model.

Indexing is slow

Embedding is the bottleneck, especially with a local model on a laptop. Use a hosted embedding provider, index less, or leave it running; it continues where it stopped.

Chat answers arrive all at once, single sign-on fails, or uploads fail Enterprise

• All at once, or hanging: the reverse proxy buffers. In nginx, proxy_buffering off.
• Single sign-on redirects to http://: the proxy is not sending X-Forwarded-Proto.
• Large uploads fail: raise the proxy's body size limit; Proxyma accepts 200 MB.
• Let's Encrypt fails (tls profile): the host name must resolve to this host with ports 80 and 443 open. Behind Cloudflare, use Full (strict), or DNS-only until the certificate is issued.

The trial did not start, or the license banner shows Enterprise

• Could not reach the license server: Proxyma keeps trying, every 15 minutes on the first day and then every 6 hours; choose Try again in Settings → License, or use a trial key.
• Trial already used: this deployment had its trial. Write to us for a license.
• Trial or license ended: see When the trial or license ends.

Getting help

Send feedback from the menu at the top right (Send feedback), or write to contact@proxyma.ai with your edition and version (Settings → About), what you expected, and what happened. For a server, add docker compose logs --tail 200 proxyma-server (or proxyma). We aim to reply within three business days.

Uninstall

Your own documents are never touched.

• Windows: uninstall from Add or remove programs. Answer Yes to delete your data too. Then delete %USERPROFILE%\.proxyma\.
• Linux: sudo apt remove proxyma, then delete ~/.local/share/proxyma/ and ~/.proxyma/.
• Home Server and Enterprise Server: docker compose down, then delete the directory. data/ and keys/ are not removed until you do.
• Kubernetes: helm uninstall. The data volume and the database password Secret are kept until you delete them.