Configuration

Komand is configured through environment variables and appsettings.json files. Environment variables take precedence, using the __ (double underscore) separator for nested keys.

Environment Variables

Core

Variable	Required	Default	Description
DOTNET_ENVIRONMENT	No	Production	Runtime environment (Development or Production)
ASPNETCORE_ENVIRONMENT	No	Production	ASP.NET Core environment (Gateway only)
ConnectionStrings__Orleans	Yes (prod)	—	PostgreSQL connection string

Authentication

Variable	Required	Default	Description
Jwt__SecretKey	Yes (prod)	Dev key	Signing key for JWT tokens (min 32 chars)
Jwt__Issuer	No	komand.ai	JWT issuer claim
Jwt__Audience	No	komand.ai	JWT audience claim
Jwt__ExpirationMinutes	No	60	Access token lifetime
Jwt__RefreshExpirationDays	No	7	Refresh token lifetime

Caution

The default JWT secret key is for development only. You must replace it in production with a cryptographically random string of at least 32 characters.

openssl rand -base64 48

Rate Limiting

Variable	Default	Description
RateLimits__ApiPermitLimit	100	Max API requests per window
RateLimits__ApiWindowSeconds	60	API rate limit window (seconds)
RateLimits__ChatPermitLimit	30	Max chat messages per window
RateLimits__ChatWindowSeconds	60	Chat rate limit window (seconds)

Rate-limited requests receive HTTP 429 Too Many Requests with the standard error envelope.

CORS

Variable	Default	Description
Cors__AllowedOrigins	(none in prod)	Allowed origins for cross-origin requests

In production, if Cors__AllowedOrigins is not set, no origins are allowed — secure by default. Set this to your dashboard domain:

Cors__AllowedOrigins=https://komand.your-domain.com

Observability

Variable	Default	Description
SEQ_URL	http://localhost:5341	Seq log ingestion URL (Docker Compose reference; .NET apps read Seq URL from Serilog config in appsettings.json)

Grain Limits

Variable	Default	Description
GrainLimits__MaxTurnsPerSession	100	Max conversation turns before trimming
GrainLimits__MaxSessionsPerAgent	100	Max active sessions before eviction
GrainLimits__MaxMemoryEntries	1000	Max memory key-value pairs per agent
GrainLimits__MaxMemoryValueLength	100000	Max characters per memory value
GrainLimits__MaxSkills	10000	Max skills in the global registry
GrainLimits__MaxToolExecutionTimeoutMinutes	30	Max skill execution timeout

Database (Docker Compose)

Variable	Default	Description
POSTGRES_DB	komand	Database name
POSTGRES_USER	komand	Database user
POSTGRES_PASSWORD	—	Database password

Frontend

Variable	Default	Description
VITE_API_URL	(same origin)	Backend API base URL
VITE_SIGNALR_URL	—	SignalR hub endpoint for real-time updates

Development vs Production

Development Mode

When DOTNET_ENVIRONMENT=Development:

Feature	Behaviour
Grain storage	In-memory (no PostgreSQL required)
Clustering	Localhost single-node
Reminders	In-memory
Swagger	Enabled at /swagger
CORS	Allows all localhost origins
Logging	Verbose, console output
JWT secret	Dev default (insecure, fine for local dev)

Development mode is designed for local development — you can run the silo and gateway without any external services.

Production Mode

When DOTNET_ENVIRONMENT=Production:

Feature	Behaviour
Grain storage	PostgreSQL via ADO.NET
Clustering	PostgreSQL ADO.NET (multi-silo capable)
Reminders	PostgreSQL ADO.NET
Swagger	Disabled
CORS	Restricted to configured origins only
Logging	Structured, shipped to Seq
JWT secret	Must be configured (startup fails if missing or insecure)
Connection string	Required (startup fails if missing)

Configuration Files

Silo (appsettings.json)

{
  "ConnectionStrings": {
    "Orleans": "Host=postgres;Database=komand;Username=komand;Password=your-password"
  },
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Orleans": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "Seq",
        "Args": { "serverUrl": "http://localhost:5341" }
      }
    ]
  },
  "GrainLimits": {
    "MaxTurnsPerSession": 100,
    "MaxSessionsPerAgent": 100,
    "MaxMemoryEntries": 1000,
    "MaxMemoryValueLength": 100000,
    "MaxSkills": 10000,
    "MaxToolExecutionTimeoutMinutes": 30
  }
}

Gateway (appsettings.json)

{
  "ConnectionStrings": {
    "Orleans": "Host=postgres;Database=komand;Username=komand;Password=your-password"
  },
  "Jwt": {
    "Issuer": "komand.ai",
    "Audience": "komand.ai",
    "SecretKey": "replace-in-production-min-32-chars",
    "ExpirationMinutes": 60,
    "RefreshExpirationDays": 7
  },
  "RateLimits": {
    "ApiPermitLimit": 100,
    "ApiWindowSeconds": 60,
    "ChatPermitLimit": 30,
    "ChatWindowSeconds": 60
  },
  "Cors": {
    "AllowedOrigins": ["https://your-domain.com"]
  },
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Orleans": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "Seq",
        "Args": { "serverUrl": "http://localhost:5341" }
      }
    ]
  }
}

Configuration Precedence

Configuration sources are loaded in this order (later sources override earlier ones):

1. appsettings.json — base defaults
2. appsettings.{Environment}.json — environment-specific overrides
3. Environment variables — highest priority

Example: GrainLimits__MaxTurnsPerSession=200 as an environment variable overrides the value in appsettings.json.

Middleware Pipeline

The Gateway processes requests through this middleware stack in order:

Order	Middleware	Purpose
1	Exception handler	Maps exceptions to HTTP status + ApiResponse<T> envelope
2	Serilog request logging	Logs request method, path, status, duration
3	CorrelationId	Reads/generates X-Request-Id, pushes to log context
4	Rate limiter	Enforces per-window request limits
5	CORS	Cross-origin request validation
6	Authentication	JWT Bearer token validation
7	Authorisation	Role and policy checks
8	UserContext	Extracts user claims, sets Orleans RequestContext
9	Static files	Serves React SPA from wwwroot/
10	Endpoints	API routes and SignalR hub
11	SPA fallback	Routes unmatched paths to index.html

Health Checks

The /health endpoint verifies:

Check	Method	Timeout
Orleans silo	Pings SkillRegistryGrain("global")	5 seconds
PostgreSQL	Connection health check	5 seconds

Returns HTTP 200 when all checks pass, HTTP 503 when any check fails.

Ports

Service	Port	Protocol	Purpose
Gateway API	5000	HTTP	REST API + Dashboard + SignalR
Orleans Silo	11111	TCP	Inter-silo communication
Orleans Gateway	30000	TCP	Client-to-silo communication
PostgreSQL	5432	TCP	Database
Seq UI	5341	HTTP	Log viewer dashboard
Seq Ingest	5342	HTTP	Log ingestion endpoint

Logging Configuration

Both the silo and gateway use Serilog with structured logging:

Setting	Default
Default level	Information
Microsoft override	Warning
Orleans override	Warning
System override	Warning
Sinks	Console + Seq
Enrichment	FromLogContext (includes correlation ID)
Silo property	Application: Komand.Silo
Gateway property	Application: Komand.Gateway

Log Level Override

To increase logging verbosity for debugging:

# Via environment variable
Serilog__MinimumLevel__Default=Debug

# Or for a specific namespace
Serilog__MinimumLevel__Override__Orleans=Information

Tuning Guide

High Message Volume

For instances handling many concurrent conversations:

GrainLimits__MaxSessionsPerAgent=500
GrainLimits__MaxTurnsPerSession=200
RateLimits__ChatPermitLimit=100
RateLimits__ChatWindowSeconds=60

Large Skill Registry

For instances with many marketplace skills:

GrainLimits__MaxSkills=50000

Long-Running Skills

For skills that need extended execution time (e.g., browser automation, data processing):

GrainLimits__MaxToolExecutionTimeoutMinutes=60

Memory-Heavy Agents

For agents that store large amounts of context:

GrainLimits__MaxMemoryEntries=5000
GrainLimits__MaxMemoryValueLength=500000