Valour is an open-source community platform built with .NET and Blazor. Communities are called planets. Each planet can have chat channels, thread feeds, wikis, voice and video calls, roles, an economy, and a village where members walk around and meet. The client supports tabs, splits, and multiple open conversations.
Use the app at app.valour.gg, install the Android app from Google Play, or visit valour.gg for the public website and the other downloads. The documentation index covers development, hosting, and architecture.
| Directory | Purpose |
|---|---|
Config/ |
Server configuration classes and a sample settings file |
Valour/Client/ |
Shared Razor UI, client services, TypeScript, styles, and assets |
Valour/Client.Blazor/ |
Browser WebAssembly host for the shared UI |
Valour/Client.Maui/ |
Native application host |
Valour/Sdk/ |
API client, models, caches, and SignalR connections |
Valour/Shared/ |
Shared contracts, permissions, requests, and utilities |
Valour/Database/ |
Entity Framework models and migrations |
Valour/Server/ |
HTTP APIs, SignalR, application services, and content delivery |
Valour/Web/ |
Public website and static exporter |
Valour/Tests/ |
C#, JavaScript, and browser tests |
Tools/Villages/ |
Artwork tools and isolated local test/server runners |
The web host references the shared client UI. The server serves API and SignalR requests and can serve the browser client and its static assets. Bots use the same SDK and API contracts as the client.
The root Docker Compose bundle includes Valour, PostgreSQL, Redis, Caddy, and filesystem media storage. Point a public domain at the host and allow inbound ports 80 and 443. From the repository root:
cp .env.example .envEdit .env to set the domain, database password, bootstrap administrator
credentials, and DATAPROTECTION__KEK, a secret key that protects the encryption
keys the server stores (generate it with openssl rand -base64 32 and keep a
copy apart from database backups; see
Data Protection KEK). Compose
refuses to start without it. Then start the services:
docker compose up -dCaddy obtains the HTTPS certificate and proxies the application. The Compose
file maps supported .env values into the container. Additional server settings,
such as S3 storage or optional integrations, need corresponding entries in the
service environment or a Compose override. Merely adding an arbitrary setting
to .env does not pass it to the application.
See Deployment for storage, optional services, and cluster operation. Self-hosted voice covers the LiveKit overlay and required media ports.
A federation hub owns accounts and the global planet registry. Registered community nodes host planets on independent domains. Clients connect directly to those nodes using destination-specific credentials issued by the hub. Their normal Valour session token stays with the hub.
To configure a community node in the Compose bundle, run:
./scripts/valour-node-setupThe wizard configures the domain and hub, creates a private Data Protection key, and asks which owners may move planets to the node. The operator then registers and verifies the public node in the hub's User Settings, Federation screen. Without federation settings, the Compose deployment runs as a standalone instance.
Planet owners start a move from their planet's Federation settings, import the signed grant, verify the destination, and finalize source deletion. Read the federation guide before moving a planet, including its transfer limits and the distinction between a pending and completed handoff.
Install the at least the suggested SDK version in global.json:
11.0.100-rc.1. Local server work also requires PostgreSQL and Redis.
JavaScript tests use Node.js, and browser tests require Playwright.
Native application builds require their platform workloads.
Restore dependencies from the repository root:
dotnet workload restore
dotnet restoreCreate the ignored Valour/Server/appsettings.json using
Config/appsettings.helper.json as a guide.
Configure Database, Redis, and Node for your local services. Choose filesystem
media storage for local uploads, and configure optional services only when needed.
The helper file is a list of settings with placeholders, not a ready-to-run config.
The server applies Entity Framework migrations on startup. Start it with:
dotnet run --project Valour/Server/Valour.Server.csprojThe development launch profile uses https://localhost:5001 and
http://localhost:5000. The server's startup output identifies the listening URLs.
The browser client resolves its API address through its hosting configuration.
The native app uses the official API unless a Debug build names a local server.
To test on a phone, start the server with the Valour.Server (phones on this network) launch profile, which also listens on port 5080 on every network
interface. Port 5000 is not used for this because macOS reserves it for the
AirPlay receiver. Then create the ignored Valour/Client.Maui/Local.props:
<Project>
<PropertyGroup>
<ValourApiBase>http://192.168.1.20:5080</ValourApiBase>
</PropertyGroup>
</Project>Use your computer's address on the network the phone shares, and rebuild the app. Debug builds on Android allow plain HTTP for this; Release builds always use the official API over HTTPS. The phone and computer must be on the same network, and the computer's firewall must allow incoming connections to the server.
The Mac app is a Mac Catalyst build of the same project. Its target is built only when a full Xcode is selected, and the .NET for Mac Catalyst workload requires a specific Xcode version; the build error names it. Build and run it with:
dotnet build Valour/Client.Maui -f net11.0-maccatalyst
open Valour/Client.Maui/bin/Debug/net11.0-maccatalyst/maccatalyst-arm64/Valour.appEncryption keys and Touch ID sign-in keys live in the Keychain, which only a build
signed with the Apple team can use. To sign, add CodesignKey (the certificate
name) and CodesignProvision (the provisioning profile name) to Local.props.
An unsigned Debug build keeps encryption keys in a file inside the app's sandbox
and offers no Touch ID sign-in. Debug builds that name a local server with
ValourApiBase may reach it over plain HTTP.
The macOS workflow builds the release disk image for Apple silicon and Intel Macs,
signs it with the Valour Software LLC Developer ID, has Apple notarize it, and
attaches Valour-macos.dmg to the version's release. It reads these repository
secrets: MACOS_CERT_P12_BASE64 and MACOS_CERT_PASSWORD (the Developer ID
Application certificate and its private key), MACOS_PROVISION_PROFILE_BASE64
(the Developer ID provisioning profile for gg.valour.app), and
ASC_API_KEY_P8_BASE64, ASC_API_KEY_ID, and ASC_API_ISSUER_ID (an App Store
Connect API key for notarization).
Build from the root with dotnet build. C# integration tests start application
services and need a dedicated test database and Redis instance. Use the
isolated test runner rather
than running them with a personal or shared server configuration. JavaScript tests
run with node --test Valour/Tests/Js/*.test.mjs after compiling the client sources.
Release builds that reference the local village atlas require the matching private art asset. Follow Village tilesets to generate or restore it before publishing.
Read Reactive models before changing model caches, events, or node connections. For server work, see API routing and Roles. Use GitHub issues for bug reports and feature discussions. Report vulnerabilities using SECURITY.md.
The name "Valour" is a trademark of Valour Software LLC, and a trademark application is pending. While the project is open-source, use of the trademark must not imply endorsement by Valour Software LLC or mislead others regarding the origin of the project.
Forks or derivative projects may not use the name "Valour" or related branding without prior written permission from Valour Software LLC. Any use of the trademark outside the scope of this project requires explicit permission.
While use of the trademark is not permitted for forks of the project itself, use of the mark is allowed for Valour bots, plugins, or integrations. If you are unsure, contact us!