Skip to main content

​
Overview

A FOKS server running in hosting_platform mode can host many virtual hosts — isolated FOKS instances that each have their own HostID, users, teams, and data, but share the underlying infrastructure (processes and database cluster). This is how foks.app operates: each organization or team gets their own virtual host with its own DNS name and cryptographic identity, without needing to operate separate hardware.

​
How virtual hosts work

Each virtual host has:
  • A unique HostID derived from its own HostKey — cryptographically distinct from the primary host
  • Its own DNS name (e.g., myorg.foks.app)
  • Isolated users, teams, and data
  • Its own invite codes, viewership settings, and (optionally) SSO configuration
Internally, virtual hosts share the same backend services (user, reg, kv_store, etc.) as the primary host. The mTLS handshake carries the HostID so the backend can route each request to the correct virtual host’s data partition. The virtual host’s host chain uses an Alias link type to point its non-probe keys (user service CA, Merkle signer, etc.) to those of the primary host. Clients verify this chain and trust the virtual host accordingly.

​
Creating a virtual host

Virtual hosts are created and managed through the web admin panel: 
foks admin web
From there, navigate to Virtual Hosts → Create. You will be prompted for:
  • A subdomain or custom domain
  • Viewership mode (open or closed)
  • Optional SSO configuration
The platform generates a new key pair, HostID, and host chain for the virtual host automatically.

​
Deployment modes

​
hosting_platform

Set --server-mode hosting_platform when running config.bash. This starts:
  • The primary host — the base instance (not intended for end users)
  • A management host (e.g., vh.foks.app) — where admins create and manage virtual hosts
  • A big-top host (e.g., foks.app) — a general-purpose instance for individual users and small teams
Additional virtual hosts can be created from the management host at runtime.

​
standalone

In standalone mode there are no virtual hosts — the server runs as a single instance. This is appropriate for a dedicated team server or self-hosted deployment.

​
DNS for virtual hosts

Each virtual host needs a DNS record pointing to the same server IP: 
myorg.foks.app    A    <server-ip>
The FOKS probe service routes clients to the correct virtual host based on the hostname in the TLS SNI, which maps to the virtual host’s HostID.

​
Per-virtual-host configuration

The following can be configured independently for each virtual host via the web admin panel:
SettingDescription
Viewership modeWhether users can see each other (open, closed)
Invite code regimeWhether signups require an invite code
SSO / OAuth2Identity provider integration (see Configuration)
Plans and quotasStorage limits and feature access

​
Custom domains (vanity hosts)

Virtual hosts can use custom domains (e.g., foks.yourcompany.com) rather than subdomains of the platform. This requires:
  1. A DNS record pointing your domain to the server IP
  2. A TLS certificate for that domain (obtained via Let’s Encrypt or provided manually)
  3. Registering the custom domain in the web admin panel
Custom domain configuration is available on the hosting_platform tier at foks.cloud.