Installation

Get up and running with Altruist in minutes.

Prerequisites

  • .NET 9 SDK or later
  • A code editor (Visual Studio, Rider, or VS Code)
  • (Optional) PostgreSQL if using database persistence

Quickest Start: Project Template

The fastest way to get a working server. One-time setup, then create projects instantly:

# Install the template (once)
dotnet new install Altruist.Templates

# Create a new project
dotnet new altruist -n MyServer
cd MyServer
dotnet run

That's it. You now have a running server with WebSocket + HTTP endpoints, a portal with two gates, and a health controller.

Note:

The template creates a complete project with Program.cs, config.yml, a WebSocket portal, and an HTTP controller — all wired and ready to run. No manual package setup needed.

What the template creates

MyServer/
  Program.cs                  # 1-line entry point
  config.yml                  # WebSocket + JSON, HTTP on port 8080
  MyServer.csproj             # Altruist packages pre-configured
  Portals/
    HelloPortal.cs            # WebSocket: hello + ping gates
  Http/
    HealthController.cs       # REST: health, hello, echo endpoints

What you'll see

 The Portals Are Open! Connect At:
----------------------------------------------------
 Address: ws://0.0.0.0:8080/ws
 Transport: WebSocket
----------------------------------------------------
 Welcome, traveler!

Now listening on: http://0.0.0.0:8080

Test it immediately

# HTTP health check
curl http://localhost:8080/api/health

# HTTP hello
curl http://localhost:8080/api/health/hello?name=Developer

# HTTP echo
curl -X POST http://localhost:8080/api/health/echo -d "Hello Altruist!"

Alternative: Altruist CLI

If you prefer a branded CLI tool:

# Install the CLI (once)
dotnet tool install -g Altruist.CLI

# Create a new project
altruist create MyServer
cd MyServer
dotnet run

Creates the same project as the template. Use whichever you prefer.

Manual Setup

If you want full control over the project structure, set it up manually:

1. Create a new .NET project

dotnet new console -n MyGameServer
cd MyGameServer

2. Add Altruist

dotnet add package Altruist --version 0.9.6-beta

3. Create your entry point

using Altruist;

await AltruistApplication.Run(args);

4. Create your configuration

altruist:
  server:
    http:
      host: "0.0.0.0"
      port: 8080
      path: "/"
    transport:
      codec:
        provider: json
      websocket:
        enabled: true
        path: /ws

Note:

Make sure config.yml is copied to the output directory. In your .csproj file add:

<ItemGroup>
  <None Update="config.yml">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

5. Run

dotnet run

Packages

PackageWhat it includesInstall
AltruistFull framework — server, networking, gaming, persistencedotnet add package Altruist --version 0.9.6-beta
Altruist.DIStandalone DI only — [Service], [PostConstruct], config bindingdotnet add package Altruist.DI --version 0.9.6-beta
Altruist.TemplatesProject template for dotnet newdotnet new install Altruist.Templates
Altruist.CLICLI tool for project scaffoldingdotnet tool install -g Altruist.CLI

Note:

Altruist includes Altruist.DI automatically. Templates and CLI are separate installs (same pattern as EF Core — the library, tool, and templates are separate NuGet packages).

Standalone DI Setup

For projects that only need dependency injection (no server, no networking):

dotnet new console -n MyWorker
cd MyWorker
dotnet add package Altruist.DI --version 0.9.6-beta

using Altruist;

await AltruistDI.Run(args);

myapp:
  database:
    connection: "Host=localhost;Database=mydb"
  feature:
    enabled: true

using Altruist;

[Service(typeof(IMyService))]
public class MyService : IMyService
{
    public MyService(
        [AppConfigValue("myapp:database:connection")] string connectionString,
        ILoggerFactory loggerFactory)
    {
        // Fully wired — config values injected, logging available
    }

    [PostConstruct]
    public async Task Initialize()
    {
        // Runs after all services are registered
    }
}

This gives you the full attribute-based DI system ([Service], [PostConstruct], [ConditionalOnConfig], [AppConfigValue], [ConfigurationProperties]) with YAML config loading — in a 150 KB package with zero server dependencies. See Services & DI for the complete API reference.

What's Next?

Head to the Quick Start Guide to build your first portal and start handling real-time connections.