Configuration

Amurg uses two JSON configuration files: one for the Hub and one for the Runtime. Both are passed via the -config flag at startup.

Hub Configuration

The hub config controls the HTTP/WebSocket server, authentication, storage, session management, logging, and rate limiting.

server

Field	Type	Default	Description
`addr`	string	required	Listen address, e.g. `":8080"`
`tls_cert`	string	`""`	Path to TLS certificate file
`tls_key`	string	`""`	Path to TLS key file
`ui_static_dir`	string	`""`	Path to built UI static files for embedded serving
`allowed_origins`	[]string	`["*"]`	CORS allowed origins
`max_body_bytes`	int64	`1048576`	Max request body size in bytes (1 MB)
`file_storage_path`	string	`"./amurg-files"`	Directory for uploaded file storage
`max_file_bytes`	int64	`10485760`	Max file upload size in bytes (10 MB)

auth

Field	Type	Default	Description
`provider`	string	`"builtin"`	Auth provider: `"builtin"` or `"clerk"`
`clerk_issuer`	string	`""`	Clerk issuer URL (required when provider is `"clerk"`)
`clerk_secret_key`	string	`""`	Clerk secret key for backend operations
`jwt_secret`	string	required	HMAC secret for signing JWT tokens (required for builtin provider)
`jwt_expiry`	duration	`"24h"`	JWT token lifetime
`runtime_tokens`	[]object	`[]`	Array of `{ runtime_id, token, name }` entries for runtime auth
`runtime_token_secret`	string	`""`	HMAC secret for time-limited runtime tokens
`runtime_token_lifetime`	duration	`"1h"`	Lifetime for generated runtime tokens
`initial_admin`	object	`null`	Bootstrap admin with `{ username, password }`
`default_endpoint_access`	string	`"all"`	Default endpoint access for new users: `"all"` or `"none"`

  storage
     Field  Type  Default  Description  
 
  driver string "sqlite" Database driver
 dsn string "amurg.db" Database connection string or file path
 retention duration "720h" Transcript retention period (30 days)
 
 
 
  SQLite In-Memory DSN
   If you use an in-memory database for testing, set the DSN to file::memory:?cache=shared instead of plain :memory:. Without the shared cache, each connection opens a separate database and tables created by one connection will not be visible to others.
  
 
  session
     Field  Type  Default  Description  
 
  max_per_user int 20 Max active sessions per user
 idle_timeout duration "30m" Global session idle timeout
 turn_based bool false Enforce turn-based messaging globally
 replay_buffer int 100 Messages buffered for WebSocket reconnect
 profile_idle_timeouts map[string]duration {} Per-profile idle timeout overrides; "0" disables
 max_message_bytes int64 65536 Max WebSocket message size from client (64 KB)
 
 
  logging
     Field  Type  Default  Description  
 
  level string "info" Log level: debug, info, warn, error
 format string "json" Output format: "json" or "text"
 
 
 
  rate_limit
     Field  Type  Default  Description  
 
  requests_per_second float64 10 Requests per second per client
 burst int 20 Burst allowance
 
 
 
 Full Hub Config Example
 {
  "server": {
    "addr": ":8090",
    "tls_cert": "",
    "tls_key": "",
    "ui_static_dir": "./ui/dist",
    "allowed_origins": ["http://localhost:3000"],
    "max_body_bytes": 1048576,
    "file_storage_path": "./amurg-files",
    "max_file_bytes": 10485760
  },
  "auth": {
    "provider": "builtin",
    "jwt_secret": "change-me-in-production",
    "jwt_expiry": "24h",
    "runtime_tokens": [
      {
        "runtime_id": "local-runtime",
        "token": "dev-token-change-me",
        "name": "Local Dev Runtime"
      }
    ],
    "runtime_token_secret": "",
    "runtime_token_lifetime": "1h",
    "initial_admin": {
      "username": "admin",
      "password": "admin"
    },
    "default_endpoint_access": "all"
  },
  "storage": {
    "driver": "sqlite",
    "dsn": "amurg.db",
    "retention": "720h"
  },
  "session": {
    "max_per_user": 20,
    "idle_timeout": "30m",
    "turn_based": true,
    "replay_buffer": 100,
    "profile_idle_timeouts": {},
    "max_message_bytes": 65536
  },
  "logging": {
    "level": "info",
    "format": "json"
  },
  "rate_limit": {
    "requests_per_second": 10,
    "burst": 20
  }
}
  Runtime Configuration
 
The runtime config tells the runtime how to connect to the hub and defines which agent endpoints to register.
  hub
     Field  Type  Default  Description  
 
  url string required Hub WebSocket URL, e.g. ws://localhost:8090/ws/runtime
 token string required Pre-shared token matching a runtime_tokens entry on the hub
 tls_skip_verify bool false Skip TLS verification (development only)
 reconnect_interval duration "2s" Initial reconnect delay
 max_reconnect_delay duration "60s" Maximum backoff delay for reconnection
 
 
 
  runtime
     Field  Type  Default  Description  
 
  id string required Unique runtime identifier, must match a runtime_tokens entry
 org_id string "default" Organization ID for multi-tenant deployments
 max_sessions int 10 Max concurrent sessions across all endpoints
 default_timeout duration "30m" Default session timeout
 max_output_bytes int64 10485760 Max output bytes per session (10 MB)
 idle_timeout duration "30s" Idle timeout for output collection
 log_level string "info" Log level: debug, info, warn, error
 file_storage_path string "./amurg-files" Directory for file storage
 max_file_bytes int64 10485760 Max file size in bytes (10 MB)
 
 
 
  endpoints[]
 
Each entry in the endpoints array defines an agent that the runtime will register with the hub.
     Field  Type  Description  
 
  id string Unique endpoint identifier (required)
 name string Human-readable display name
  profile  string  
Adapter profile (required). One of:
"generic-cli",
"generic-job",
"generic-http",
"external",
"claude-code",
"github-copilot",
"codex",
"kilo-code"  
 tags map[string]string Arbitrary key-value metadata
 limits object Per-endpoint operational limits (see below)
 security object Security constraints for this endpoint (see below)
 
 
 
 
Each endpoint also includes a profile-specific config key. The key must match the profile:
     Profile  Config Key  
 
  generic-cli cli
 generic-job job
 generic-http http
 external external
 claude-code claude_code
 github-copilot copilot
 codex codex
 kilo-code kilo
 
 
 
  Tip
   For detailed adapter config fields and examples for each profile, see the Adapters page.
  
 
  limits (per-endpoint)
     Field  Type  Default  Description  
 
  max_sessions int 0 (unlimited) Max concurrent sessions for this endpoint
 session_timeout duration "0" (uses runtime default) Override session timeout for this endpoint
 max_output_bytes int64 0 (uses runtime default) Override max output bytes for this endpoint
 idle_timeout duration "0" (uses runtime default) Override idle timeout for this endpoint
 
 
 
  security (per-endpoint)
 
The optional security block on each endpoint defines filesystem, tool, and environment constraints for the agent process.
     Field  Type  Default  Description  
 
  allowed_paths []string [] Filesystem paths the agent may access
 denied_paths []string [] Filesystem paths denied to the agent
 allowed_tools []string [] Tools the agent is allowed to use
 permission_mode string "" Permission enforcement mode: "skip", "strict", or "auto"
 cwd string "" Override working directory for the agent
 env_whitelist []string [] Environment variables passed to the agent
 
 
 
 Full Runtime Config Example
 {
  "hub": {
    "url": "ws://localhost:8090/ws/runtime",
    "token": "dev-token-change-me",
    "tls_skip_verify": false,
    "reconnect_interval": "2s",
    "max_reconnect_delay": "60s"
  },
  "runtime": {
    "id": "local-runtime",
    "org_id": "default",
    "max_sessions": 10,
    "default_timeout": "30m",
    "max_output_bytes": 10485760,
    "idle_timeout": "30s",
    "log_level": "info",
    "file_storage_path": "./amurg-files",
    "max_file_bytes": 10485760
  },
  "endpoints": [
    {
      "id": "my-agent",
      "name": "My CLI Agent",
      "profile": "generic-cli",
      "tags": { "env": "dev" },
      "limits": {
        "max_sessions": 5,
        "session_timeout": "1h",
        "max_output_bytes": 5242880,
        "idle_timeout": "10m"
      },
      "security": {
        "allowed_paths": ["/home/user/projects"],
        "denied_paths": ["/etc", "/root"],
        "allowed_tools": [],
        "permission_mode": "auto",
        "cwd": "/home/user/projects",
        "env_whitelist": ["PATH", "HOME"]
      },
      "cli": {
        "command": "/usr/local/bin/my-agent",
        "args": ["--interactive"],
        "work_dir": "/home/user/projects",
        "env": { "AGENT_MODE": "chat" },
        "spawn_policy": "per-session"
      }
    }
  ]
}

Profile	Config Key
`generic-cli`	`cli`
`generic-job`	`job`
`generic-http`	`http`
`external`	`external`
`claude-code`	`claude_code`
`github-copilot`	`copilot`
`codex`	`codex`
`kilo-code`	`kilo`

Field	Type	Default	Description
`driver`	string	`"sqlite"`	Database driver
`dsn`	string	`"amurg.db"`	Database connection string or file path
`retention`	duration	`"720h"`	Transcript retention period (30 days)

Field	Type	Default	Description
`max_per_user`	int	`20`	Max active sessions per user
`idle_timeout`	duration	`"30m"`	Global session idle timeout
`turn_based`	bool	`false`	Enforce turn-based messaging globally
`replay_buffer`	int	`100`	Messages buffered for WebSocket reconnect
`profile_idle_timeouts`	map[string]duration	`{}`	Per-profile idle timeout overrides; `"0"` disables
`max_message_bytes`	int64	`65536`	Max WebSocket message size from client (64 KB)

Field	Type	Default	Description
`level`	string	`"info"`	Log level: debug, info, warn, error
`format`	string	`"json"`	Output format: `"json"` or `"text"`

Field	Type	Default	Description
`requests_per_second`	float64	`10`	Requests per second per client
`burst`	int	`20`	Burst allowance

Field	Type	Default	Description
`url`	string	required	Hub WebSocket URL, e.g. `ws://localhost:8090/ws/runtime`
`token`	string	required	Pre-shared token matching a `runtime_tokens` entry on the hub
`tls_skip_verify`	bool	`false`	Skip TLS verification (development only)
`reconnect_interval`	duration	`"2s"`	Initial reconnect delay
`max_reconnect_delay`	duration	`"60s"`	Maximum backoff delay for reconnection

Field	Type	Default	Description
`id`	string	required	Unique runtime identifier, must match a `runtime_tokens` entry
`org_id`	string	`"default"`	Organization ID for multi-tenant deployments
`max_sessions`	int	`10`	Max concurrent sessions across all endpoints
`default_timeout`	duration	`"30m"`	Default session timeout
`max_output_bytes`	int64	`10485760`	Max output bytes per session (10 MB)
`idle_timeout`	duration	`"30s"`	Idle timeout for output collection
`log_level`	string	`"info"`	Log level: debug, info, warn, error
`file_storage_path`	string	`"./amurg-files"`	Directory for file storage
`max_file_bytes`	int64	`10485760`	Max file size in bytes (10 MB)

Field	Type	Description
`id`	string	Unique endpoint identifier (required)
`name`	string	Human-readable display name
`profile`	string	Adapter profile (required). One of: `"generic-cli"`, `"generic-job"`, `"generic-http"`, `"external"`, `"claude-code"`, `"github-copilot"`, `"codex"`, `"kilo-code"`
`tags`	map[string]string	Arbitrary key-value metadata
`limits`	object	Per-endpoint operational limits (see below)
`security`	object	Security constraints for this endpoint (see below)

Field	Type	Default	Description
`max_sessions`	int	`0` (unlimited)	Max concurrent sessions for this endpoint
`session_timeout`	duration	`"0"` (uses runtime default)	Override session timeout for this endpoint
`max_output_bytes`	int64	`0` (uses runtime default)	Override max output bytes for this endpoint
`idle_timeout`	duration	`"0"` (uses runtime default)	Override idle timeout for this endpoint

Field	Type	Default	Description
`allowed_paths`	[]string	`[]`	Filesystem paths the agent may access
`denied_paths`	[]string	`[]`	Filesystem paths denied to the agent
`allowed_tools`	[]string	`[]`	Tools the agent is allowed to use
`permission_mode`	string	`""`	Permission enforcement mode: `"skip"`, `"strict"`, or `"auto"`
`cwd`	string	`""`	Override working directory for the agent
`env_whitelist`	[]string	`[]`	Environment variables passed to the agent