Skip to content
ConceptForEveryoneWith or without Foxden Admin

The parts of Foxden ​

This page shows you what Foxden is made of and how the parts talk to each other, so you can reason about what happens on your server before you install it or change it.

Foxden is a set of separate apps on one server. Each app (Fennec, Arctic, Corsac, Pampas, Culpeo, Cape and Library) is its own program with its own database, and each can run alone. Foxden Admin joins them: it signs people in, holds the company's people and settings, and is the one door for AI and for assistants. Every request one part sends another is signed, and no app waits on Admin to answer a person's request.

The diagram ​

text
        browsers                                 AI assistants (MCP clients)
           |                                               |
   +-------v-----------------------------------------------v--------+
   |  proxy on ports 80 and 443: one address per app, certificates  |
   +-------+-----------------------------------------------+--------+
           |                                               |
   +-------v-----------------------------------------------v--------+
   |  Foxden Admin                                                   |
   |  sign-in  |  console  |  feeds  |  AI gateway  |  MCP gateway   |
   |  events router  |  activity log  |  control service            |
   +----^--------------------^---------------------^------------+---+
        | sign-in, feeds,    | calls recorded,     | per-call   | runs
        | AI requests        | events, activity    | token      | foxden
        |                    |                     v            v commands
   +----+--------+--------+--------+--------+-------+------+---------+
   | Fennec | Arctic | Corsac | Pampas | Culpeo | Cape | Library      |
   | each: its own database and its own updater                     |
   +---+-------------+--------+--------+--------------------+--------+
       |             files: Fennec, Corsac, Pampas, Culpeo  |
       |             and Admin keep their bytes in Library  |
       |                                                    v
       +-- HTML to print --> renderer (PDF) <-- HTML ---- Library

The parts ​

The apps ​

Each app is a web app with its own Postgres database, listening only on the server's loopback address. It keeps its own users table, its own sessions and its own settings, and it decides what each person can do inside it. An app that is not connected to Admin keeps its own sign-in and its own People page.

The proxy ​

One proxy owns ports 80 and 443 and forwards each address to the app behind it. When you install with foxden, each app gets an address under one domain: admin., crm. (Fennec), meet. (Arctic), sign. (Corsac), forms. (Pampas), agent. (Culpeo), calls. (Cape) and library.. The proxy gets certificates from Let's Encrypt, or uses its own certificate authority on an office network. See Install Foxden on your server.

Foxden Admin ​

Admin is a component every connected app relies on, without being in the way of any of them:

  • Sign-in issuer. An app sends a person to Admin to sign in and gets back a short signed statement of who they are and what level they hold. See Key flows, end to end.
  • Feeds. Each app reads three things from Admin about once a minute: who may use it (the access feed), the company's name and brand (the workspace profile), and each person's name and photo (the people profile). An app answers from what it last read, so Admin being down costs freshness, not a page.
  • AI gateway. Every app's AI requests go through Admin, which holds the provider keys, the limits and the record of what was spent. With no provider key in Admin, AI is off in every app.
  • MCP gateway. One connection for an AI assistant reaches every app the person can use, acting as that person. See The AI gateway.
  • Events router. Apps report events such as "a document was signed" to Admin, which sends them on to the addresses an Owner sets. See Send events to another system.
  • Activity log. Admin reads each app's own activity log and shows them together.
  • Console and control service. The Owner runs the company and the server from Admin's console. Server changes go through a small control service that runs the same foxden commands an operator would type. See Foxden Admin, the console.

Library as the file store ​

Library is an app people use for pages and files, and it is also where Fennec, Corsac, Pampas, Culpeo and Admin keep the bytes of their files once the server links them. See Library as the file store.

The updater ​

Every app's stack carries the same small updater container. It pulls a new build, takes a snapshot of the database, starts the new build, waits for it to report the new version, and puts the database and the previous build back if it does not. foxden update, Admin's Update buttons and automatic updates all ask it the same way. See Update Foxden.

The renderer ​

The renderer turns HTML into PDF with a headless Chromium. Library runs one for PDF exports; Fennec runs one, when you turn it on, for quote PDFs. It sits on an internal network with no route off the server, runs read-only as a user that is not root with no Linux capabilities, and aborts every request the page makes except to data: addresses, so a document cannot fetch anything while it prints.

The foxden command line ​

foxden installs the apps, writes each one's settings file, wires them to each other, backs them up and updates them. It runs on the server or from your own computer over SSH. See foxden command line.

How the parts trust each other ​

  • One box key. foxden init makes a random key in /etc/foxden/box.key once. The secrets that link one app to another are derived from it, one per link, and written only into the two apps on that link. Each app's link to Admin has a secret of its own, which foxden init writes into that app and Admin.
  • Signed requests. Feeds, file requests, AI requests, events and updates are each signed with the sending app's own secret over the time and the request, so one app cannot speak as another and an old request cannot be replayed.
  • Admin is never on a request path. Apps read from Admin on their own schedule and keep the last good answer. A person's page in Fennec never waits for Admin.

Foxden is open source under Apache-2.0.