Autostart

Hermes can register your application to launch automatically when the user logs in. A single method call handles the platform-specific plumbing — macOS LaunchAgents, Windows Registry, and Linux XDG autostart entries — so your app starts on boot without manual setup.

Quick Reference

using Hermes;

// Enable autostart (app ID detected from entry assembly)
Autostart.SetEnabled(true);

// Check if autostart is enabled
bool enabled = Autostart.IsEnabled;

// Disable autostart
Autostart.SetEnabled(false);

Or with the Blazor app builder:

HermesBlazorApp.CreateBuilder(args)
    .UseAutostart()
    .Build()
    .Run();

Enabling and Disabling

The simplest overload detects your app ID from the entry assembly name:

Autostart.SetEnabled(true);   // register
Autostart.SetEnabled(false);  // unregister

For explicit control over the app ID:

Autostart.SetEnabled("my-app", true);
Autostart.SetEnabled("my-app", false);

The app ID determines the registration name on each platform (plist label, registry key, or desktop file name). Using a consistent ID ensures enable/disable pairs match correctly.

Checking Status

// Auto-detected app ID
if (Autostart.IsEnabled)
{
    Console.WriteLine("App will launch at login");
}

// Explicit app ID
bool enabled = Autostart.GetIsEnabled("my-app");

Launch Arguments

You can pass command-line arguments that your app receives when launched at login. This is useful for starting in a background or minimized state:

Autostart.SetEnabled(true, args: ["--background", "--minimized"]);

// With explicit app ID
Autostart.SetEnabled("my-app", true, args: ["--minimized"]);

Your app can then check for these arguments on startup:

if (args.Contains("--minimized"))
{
    window.StartMinimized();
}

Blazor Integration

The UseAutostart extension method on HermesBlazorAppBuilder registers autostart during app setup:

var builder = HermesBlazorApp.CreateBuilder(args);

// Auto-detect app ID
builder.UseAutostart();

// Or with explicit app ID and launch arguments
builder.UseAutostart("my-app", args: ["--background"]);

builder.Build().Run();

Platform Details

Platform	Mechanism	Location
macOS	LaunchAgent plist with RunAtLoad	~/Library/LaunchAgents/{appId}.plist
Windows	Registry entry (current user)	HKCU\Software\Microsoft\Windows\CurrentVersion\Run
Linux	XDG Desktop Entry	~/.config/autostart/{appId}.desktop

No elevated permissions are required on any platform — all registrations are scoped to the current user.

macOS and Windows

On macOS, Hermes writes a standard LaunchAgent plist — no entitlements or notarization changes needed. On Windows, it writes to HKCU (current user), so no administrator privileges are required.

Linux XDG

On Linux, Hermes respects the XDG_CONFIG_HOME environment variable. If unset, it defaults to ~/.config. The autostart directory is created automatically if it doesn't exist.

Error Handling

Exception	Cause
ArgumentException	App ID is null, empty, or whitespace
InvalidOperationException	Entry assembly name or Environment.ProcessPath cannot be determined
PlatformNotSupportedException	OS is not Windows, macOS, or Linux

Example: Tray App with Autostart

A tray application that starts at login and runs in the background:

using Hermes;

Autostart.SetEnabled("my-tray-app", true, args: ["--background"]);

var window = HermesWindow.Create()
    .WithTitle("My Tray App")
    .AsTrayApplication()
    .WithSize(400, 300);

if (args.Contains("--background"))
{
    window.StartMinimized();
}

window.Load("wwwroot/index.html").Run();

Next Steps

• Tray Applications — build apps that live in the system tray
• Single Instance — prevent duplicate instances when autostart triggers
• Crash Reporting — monitor crashes in always-running apps