Configuration Reference

This document lists all configurable options in Elftia, grouped by functional domain.

---

Environment Variables

Frontend (Vite / VITE_*)

Frontend environment variables are exposed with the VITE_ prefix and can be accessed in React code via import.meta.env.

Variable	Type	Default	Description
VITE_APP_TITLE	string	'Elftia'	Application title
VITE_DEV_PORT	number	5375	Vite Dev Server port

Backend (Main Process)

Variable	Type	Default	Description
LOG_LEVEL	string	'info'	Log level (debug / info / warn / error)
NODE_ENV	string	'development'	Runtime environment
ELECTRON_IS_DEV	string	'1'	Whether running in development mode

---

App Preferences (AppPreferences)

Read/write via window.api.appPreferences. Stored in the SQLite database.

Field	Type	Default	Description
sendByCtrlEnter	boolean	false	Send messages with Ctrl+Enter
autoScrollToBottom	boolean	true	Auto-scroll to the bottom on new messages
showThinking	boolean	true	Show the model's thinking process
autoExpandTools	boolean	false	Auto-expand tool call details
showRawParameters	boolean	false	Show raw parameters for tool calls

---

Theme Configuration (Theme)

Read/write via window.api.theme. Full state structure:

Mode

Field	Type	Default	Description
mode	'light' | 'dark' | 'system'	'system'	Theme mode

User Custom Theme (UserTheme)

Field	Type	Description
colors	Record<string, string>	Custom color token overrides
fonts	{ ui?: string; code?: string; display?: string }	Custom fonts

Custom CSS

Field	Type	Default	Description
customCss	string	''	User-injected custom CSS

Wallpaper

All wallpaper-related fields reside in ThemePreferencesSchema (packages/desktop/app/main/services/platform/config/store/configSchema.ts), stored at config.theme, and partially updated via IPC theme:setWallpaperPreferences. See packages/desktop/app/shared/contracts/settings-types.ts → ThemePreferences for the source definition.

Wallpaper Source (Image / Gradient)

Field	Type	Default	Description
wallpaper	{ light?: string; dark?: string }	{}	Image wallpaper source; supports file://, wallpaper:// protocols, data: URLs, or whitelisted https:// URLs
wallpaperGradient	{ stops: string[1..4]; angle?: number 0..360 }	null	1–4 color linear gradient; takes priority over wallpaper; enabling it temporarily hides the image
disableWallpaperInCompactWindows	boolean	false	Disable wallpaper in compact windows (Mini/Selection)
wallpaperOverlayEnabled	boolean	false	Enable translucent surfaces (better suited for wallpaper mode)

Frosted Glass & Overlay

Field	Type	Range	Default	Description
wallpaperBlurIntensity	number	0–30	6	Frosted glass blur in px
wallpaperDimming	number	0–100	70	Overall overlay opacity %
wallpaperDimmingHue	number	0–360	0	Overlay HSL hue (decoded from hex color picker)
wallpaperDimmingSaturation	number	0–100	0	Overlay HSL saturation %
wallpaperDimmingLightness	number	-1–100	-1	Overlay HSL lightness %; -1 = auto (white in light mode, black in dark mode); 0–100 = manual
wallpaperDimmingGradient	WallpaperGradient | null	—	null	Gradient overlay; when enabled it overrides the HSL above, but wallpaperDimming still controls overall opacity

Element Background Tint (Sidebar / Cards / Tabs and other translucent surfaces)

Field	Type	Default	Description
wallpaperElementTint	string (#RRGGBB or '')	''	Element surface tint; empty string = use theme default (warm cream / warm charcoal)
wallpaperElementGradient	WallpaperGradient | null	null	Element gradient; overrides solid tint; each tier keeps its own alpha

Message Bubbles (User / Assistant independently)

Field	Type	Default	Description
wallpaperBubbleOverride	boolean	false	Master switch: true = bubbles use the independent fields below; false = bubbles follow element background settings (color + default opacity)
wallpaperBubbleTintUser	string (#RRGGBB or '')	''	User bubble solid color; active when override is on
wallpaperBubbleTintAssistant	string (#RRGGBB or '')	''	Assistant bubble solid color; active when override is on
wallpaperBubbleGradientUser	WallpaperGradient | null	null	User bubble gradient; overrides solid color on this side
wallpaperBubbleGradientAssistant	WallpaperGradient | null	null	Assistant bubble gradient; overrides solid color on this side
wallpaperBubbleOpacity	number 0–100	35	Bubble fill alpha; only active when override is on

Overall Element Opacity

Field	Type	Range	Default	Description
wallpaperElementOpacity	number	0–100	0	Experimental: pushes translucent UI overall toward opaque
wallpaperTransparency	number	0–100	100	Surface tint intensity coefficient (0 = fully transparent surface; 100 = default alpha)

Hex / Gradient Validation

• Hex fields (wallpaperElementTint / wallpaperBubbleTint*) Zod regex: /^(#[0-9a-fA-F]{6})?$/ (empty string or #RRGGBB).
• WallpaperGradient.stops requires 1–4 strings; the backend ThemeService.setWallpaperPreferences also discards empty string stops and truncates the array to 4 items.
• In the IPC payload for gradient fields, null = clear; omitting the key = keep current value. The backend distinguishes these via 'wallpaperDimmingGradient' in patch.

Priority (Rendering Override Order)

wallpaperGradient    >  wallpaper.{light,dark}                  // main wallpaper source
wallpaperDimmingGradient  >  wallpaperDimming{Hue,Saturation,Lightness}  // overlay color
wallpaperElementGradient  >  wallpaperElementTint                // element tint
wallpaperBubbleGradient{User,Assistant}  >  wallpaperBubbleTint{User,Assistant}  // bubble color (only when override is on)

When wallpaperBubbleOverride=false, the downstream data-wp-bubble-override attribute is not written to body, and CSS falls back to the "bubbles inherit element tint" rule.

---

LLM Configuration

Provider (ProviderConfig)

Configuration structure for each LLM provider:

Field	Type	Description
id	string	Unique identifier
name	string	Display name
type	string	Provider type (openai / anthropic / google / deepseek, etc.)
apiKey	string	API key (stored on the backend, not transmitted via IPC)
baseUrl	string?	Custom API endpoint
models	Model[]	Available model list
enabled	boolean	Whether enabled

Global Model Parameters (GlobalModelParameters)

Field	Type	Range	Default	Description
temperature	number	0 - 2	Provider default	Generation temperature
maxTokens	number	1 - model limit	Provider default	Maximum output token count
topP	number	0 - 1	Provider default	Top-P sampling
topK	number	1 - 100	Provider default	Top-K sampling (some providers)
frequencyPenalty	number	-2 - 2	0	Frequency penalty
presencePenalty	number	-2 - 2	0	Presence penalty

API Key Pool (ApiKeyEntry)

Configuration for each key entry:

Field	Type	Default	Description
id	string	Auto-generated	Unique key identifier
providerId	string	-	Owning provider ID
label	string?	-	Key label
apiKey	string	-	Key value (encrypted storage)
weight	number	1	Weight (1–100); affects round-robin distribution probability
enabled	boolean	true	Whether enabled

Key pool behavior:

• Uses Weighted Round-Robin to distribute keys
• Session affinity: same session preferentially uses the same key
• 429/529 responses automatically switch to the next key
• Exponential backoff cooldown: 60s → 2min → 5min → 15min

---

Agent Configuration

TinyElf Engine Defaults

Field	Type	Default	Description
maxIterations	number	40	Maximum iteration count
temperature	number	0.1	Generation temperature
maxTokens	number	8192	Maximum output token count
toolResultMaxChars	number	50000	Maximum characters in tool results

Claude SDK Engine

Field	Type	Description
permissionMode	string	Permission mode (ask / auto-approve / deny)
maxTurns	number	Maximum conversation turns
systemPromptAppend	string?	Content to append to the system prompt

---

Security Configuration

GuardianAgent

Field	Type	Description
mode	'off' | 'monitor' | 'enforce'	Operating mode
allowedCommands	string[]	Allowlist of commands that may be executed
blockedPaths	string[]	Path patterns that are blocked from access

PromptGuardian

Field	Type	Description
mode	'off' | 'warn' | 'block'	Operating mode

RateLimiter

Field	Type	Default	Description
maxRequestsPerMinute	number	60	Maximum requests per minute
maxTokensPerMinute	number	100000	Maximum tokens per minute

---

MCP Configuration (McpServerConfig)

Configuration structure for each MCP server:

Field	Type	Description
id	string	Unique identifier
name	string	Display name
transport	'stdio' | 'sse' | 'streamable-http'	Transport protocol
command	string?	Startup command (stdio mode)
args	string[]?	Command arguments (stdio mode)
env	Record<string, string>?	Environment variables (stdio mode)
url	string?	Server URL (sse / streamable-http mode)
enabled	boolean	Whether enabled
autoConnect	boolean	Auto-connect on app startup

---

Cron Scheduled Tasks

Schedule Configuration

Field	Type	Description
schedule	string	Cron expression (5/6-field format)
timezone	string?	Timezone identifier (e.g. Asia/Tokyo)
enabled	boolean	Whether enabled

Action Types

Type	Description
agent-run	Run the specified Agent
channel-check	Check Channel messages
custom-script	Run a custom script

---

Channel Configuration

Trigger Modes

Mode	Description
mention	Respond only when @-mentioned
keyword	Respond when a keyword is present
all	Respond to all messages

Platform Message Length Limits

Platform	Max Characters
Discord	2000
Telegram	4096
Slack	40000
Custom Webhook	Unlimited

---

CSS Variables (Tailwind Tokens)

Defined in packages/renderer/src/app/index.css and mapped to utility classes via the Tailwind configuration.

Color Tokens

CSS Variable	Tailwind Class	Description
--background	bg-background	Page main background
--foreground	text-foreground	Primary text color
--surface-0	bg-surface-0	L0 layer background
--surface-1	bg-surface-1	L1 layer background (cards/sidebar)
--surface-2	bg-surface-2	L2 layer background (inputs/secondary containers)
--surface-3	bg-surface-3	L3 layer background (popovers)
--text-strong	text-foreground	Primary headings, body text (93% brightness)
--text-muted	text-muted-foreground	Secondary text (65% brightness)
--text-subtle	text-text-subtle	Auxiliary hints (50% brightness)
--primary	bg-primary / text-primary	Theme color
--secondary	bg-secondary	Secondary color
--destructive	text-destructive	Error/destructive color
--success	text-success	Success color
--warning	text-warning	Warning color
--border	border-border	Border color
--ring	ring-ring	Focus ring color
--muted	bg-muted	Muted background
--accent	bg-accent	Accent background
--popover	bg-popover	Popover background
--card	bg-card	Card background

Fonts

CSS Variable	Tailwind Class	Font
--font-sans	font-sans	Inter, system-ui
--font-mono	font-mono	JetBrains Mono, monospace
--font-display	font-display	Noto Serif, Georgia, serif
--font-ui	font-ui	User-customized UI font
--font-code	font-code	User-customized code font

Border Radius

CSS Variable	Tailwind Class	Value
--radius	rounded-lg	0.5rem (8px)
-	rounded-md	0.375rem (6px)
-	rounded-sm	0.25rem (4px)
-	rounded-xl	0.75rem (12px)

---

File Config (ConfigStore)

Read/write via window.api.config. Stored in a JSON file with hot-reload support.

When configuration changes, the main process notifies the frontend via the config:changed channel.

Common Config Keys

Key	Type	Description
magi	MagiConfig	Magi/Claw Agent configuration
magi.promptVersion	'v1' | 'v2' | 'v3' | 'v4'	Prompt build version
cron	CronConfig	Cron scheduled task configuration
channel	ChannelConfig	Channel messaging configuration
security	SecurityConfig	Security control configuration

tip

The full config file path can be retrieved via window.api.config.getPath().