Configuration

Environment variables and configuration options for Skilder deployments — backend, frontend, runtime, and infrastructure.

This reference covers the environment variables for each Skilder component.

Backend

The backend runs a Fastify server with Apollo GraphQL.

Variable	Description	Default
`PORT`	HTTP port	`3000`
`DGRAPH_URL`	Dgraph database endpoint	`localhost:8080`
`NATS_SERVERS`	NATS server address	`localhost:4222`
`ENCRYPTION_KEY`	Key for encrypting secrets (API keys, OAuth tokens, MCP server configs). Required.	--
`JWT_PRIVATE_KEY_PATH`	Path to Ed25519 private key for signing JWTs	--
`JWT_PUBLIC_KEY_PATH`	Path to Ed25519 public key for verifying JWTs	--
`JWT_ISSUER`	Issuer claim for JWT tokens	`skilder-platform`
`JWT_ACCESS_TOKEN_TTL`	Access token TTL in seconds	`900` (15 min)
`JWT_REFRESH_TOKEN_TTL`	Refresh token TTL in seconds	`604800` (7 days)
`LOG_LEVEL`	Logging verbosity: `trace`, `debug`, `info`, `warn`, `error`	`info`
`CORS_ORIGINS`	Allowed CORS origins (comma-separated)	`http://localhost:8888,http://localhost:3000`
`RUNTIME_MCP_URL`	URL for the MCP runtime endpoint	`http://localhost:3001/mcp`
`FRONTEND_URL`	Frontend URL (used for email links, OAuth callbacks)	--
`EMAIL_PROVIDER`	Email provider: `log` (console) or `resend`	`log`
`RESEND_API_KEY`	Resend API key (when `EMAIL_PROVIDER=resend`)	--
`EMAIL_FROM`	Sender email (when `EMAIL_PROVIDER=resend`)	--

Example

PORT=3000
DGRAPH_URL=localhost:8080
NATS_SERVERS=localhost:4222
ENCRYPTION_KEY=your-64-char-hex-encryption-key
JWT_PRIVATE_KEY_PATH=./keys/private.pem
JWT_PUBLIC_KEY_PATH=./keys/public.pem
JWT_ISSUER=skilder-platform
LOG_LEVEL=info
CORS_ORIGINS=https://app.yourdomain.com
RUNTIME_MCP_URL=http://localhost:3001/mcp
FRONTEND_URL=https://app.yourdomain.com
EMAIL_PROVIDER=resend
RESEND_API_KEY=re_your_api_key_here
EMAIL_FROM=noreply@yourdomain.com

Frontend

The frontend is a React + Vite application.

Variable	Description	Default
`VITE_BACKEND_HOST`	Backend host (build-time). Format: `hostname:port`	`localhost:3000`
`BACKEND_HOST`	Backend host (runtime, Docker). Overrides `VITE_BACKEND_HOST`	--
`VITE_BACKEND_HOST_SSL`	Enable SSL for backend connections	`false`

The frontend derives HTTP and WebSocket URLs from the backend host automatically.

Example

# Build-time
VITE_BACKEND_HOST=api.yourdomain.com
VITE_BACKEND_HOST_SSL=true

# Runtime (Docker)
BACKEND_HOST=api.yourdomain.com

Runtime

The runtime executes MCP servers and routes tool calls. Its mode is determined by which environment variables are set.

Mode Selection

Variable	Effect
`USER_KEY`	Activates MCP_STDIO mode (single agent, stdio transport)
`RUNTIME_KEY` or `SYSTEM_KEY`	Activates EDGE mode (NATS-connected tool executor)
`REMOTE_PORT`	Adds HTTP exposure (SSE + Streamable HTTP). Combined with a key = EDGE_MCP_STREAM; alone = STANDALONE_MCP_STREAM

Core Configuration

Variable	Description	Default
`NATS_SERVERS`	NATS cluster address	`localhost:4222`
`REMOTE_PORT`	HTTP port for SSE/Streamable HTTP	-- (disabled)
`RUNTIME_NAME`	Human-readable name (required with `SYSTEM_KEY`)	--
`LOG_LEVEL`	Logging verbosity	`info`
`LOG_LEVELS`	Pattern-based log levels (e.g., `mcp.=debug,tool.=trace`)	--
`FORWARD_STDERR`	Forward child process stderr to runtime log	`false`
`HEARTBEAT_INTERVAL`	Health heartbeat interval in ms	`5000`
`RUNTIME_MCP_URL`	MCP endpoint for delegate client connections	`http://localhost:3001/mcp`

Preloading

Variable	Description	Default
`SKILL_IDS`	Comma-separated skill IDs to auto-disclose	--
`HAT_IDS`	Comma-separated hat IDs to auto-disclose	--

File Service

Variable	Description	Default
`SKILDER_WORKING_DIR`	Working directory for temp files and assets	`/tmp/skilder`
`SKILDER_ALLOWED_PATHS`	Colon-separated path safelist for file access	--
`SKILDER_MAX_FILE_SIZE_MB`	Max file size for operations	`10`
`SKILDER_GC_INTERVAL_MS`	Garbage collection check interval	`60000` (1 min)
`SKILDER_GC_MAX_AGE_MS`	Max age for temp files before cleanup	`300000` (5 min)
`SKILDER_ASSET_CACHE_MAX_AGE_MS`	Asset cache TTL	`3600000` (1 hour)

Security

Variable	Description	Default
`SKILDER_ALLOWED_ORIGINS`	Allowed origins for HTTP transports	--
`SKILDER_PREVENT_DNS_REBINDING`	Enable origin validation against DNS rebinding	`true`
`SKILDER_SESSION_IDLE_TIMEOUT_MS`	Session cleanup timeout	`300000` (5 min)

Example

# EDGE mode with HTTP exposure
RUNTIME_KEY=RTK_your_runtime_key
NATS_SERVERS=nats://nats.yourdomain.com:4222
REMOTE_PORT=3001
LOG_LEVEL=info
SKILDER_WORKING_DIR=/tmp/skilder
SKILDER_ALLOWED_ORIGINS=https://app.yourdomain.com

Infrastructure Services

Dgraph (Graph Database)

Deploy with at least one Zero node and one Alpha node.

Port	Description	Default
Alpha HTTP	Query and mutation endpoint	`8080`
Alpha gRPC	Internal replication	`9080`
Zero gRPC	Cluster coordination	`5080`

NATS (Message Bus)

Variable	Description	Default
`NATS_PORT`	Client connection port	`4222`
`NATS_HTTP_PORT`	HTTP monitoring port	`8222`
`NATS_JETSTREAM`	Enable JetStream for persistent messaging	`true`

Security Notes

Never commit secrets to version control. Use a secrets manager or .env files.
Change the default ENCRYPTION_KEY immediately. The default key is for development only — using it in production compromises all encrypted data.
Generate a strong ENCRYPTION_KEY: 64-character hex string (32 random bytes).
Set up JWT keys: Generate an Ed25519 key pair for JWT signing. See agent_docs/key-management.md for details.
Restrict CORS_ORIGINS in production to your exact frontend domain.
Use TLS for NATS and Dgraph connections in production.

On this page