Configuration
This page is a reference for all Wings configuration options. The configuration file is located at /etc/calagopus-wings/config.yml on Linux (C:\ProgramData\Calagopus-Wings\config.yml on Windows).
Migrating from Pterodactyl/Pelican
If no -c/--config flag is passed and /etc/calagopus-wings/config.yml doesn't exist, Wings automatically looks for a config at /etc/pterodactyl/config.yml, then /etc/pelican/config.yml, then ./config.yml, in that order, and uses the first one it finds. This means an existing Pterodactyl or Pelican Wings install keeps working without moving its config file, though it's recommended to migrate to the calagopus-wings path when convenient.
Environment Overrides
Wings accepts configuration overrides through environment variables prefixed with CALAGOPUS_. Uppercase the key and replace dots with underscores: api.port becomes CALAGOPUS_API_PORT, and system.backups.s3.streaming becomes CALAGOPUS_SYSTEM_BACKUPS_S3_STREAMING.
environment:
CALAGOPUS_API_PORT: '8080'
CALAGOPUS_SYSTEM_BACKUPS_S3_STREAMING: 'false'
CALAGOPUS_ALLOWED_DEVICES: '[/dev/dri/renderD128]'This example belongs under the Wings service in Docker Compose. For a native service, set the variables in its service environment. String fields take the value literally; other fields accept YAML values such as false, 8080, or a list. Set a whole map or list when adding entries. Unknown variable names produce a warning and are ignored; invalid values for a recognized option prevent the configuration from loading.
Overrides apply when Wings loads or replaces its configuration, including updates from the Panel, and are saved into config.yml. Removing a variable leaves its last saved value in the file; edit the file as well if you want to undo the override.
On a fresh installation without a configuration file, Wings waits for pairing with the Panel. WINGS_ENROLL_PANEL_URL and WINGS_ENROLL_CODE can enroll it automatically during that first start. These enrollment variables are separate from CALAGOPUS_ configuration overrides. Pairing and enrollment write uuid, token_id, token and remote for you.
Core Configuration
debug Optional
Enables debug mode for Wings. When enabled, detailed logs are printed for troubleshooting.
Default: false
app_name Optional
A human-readable name for this Wings instance used to identify the node in log outputs.
Default: Calagopus
uuid Required
Unique identifier for this Wings node.
token_id Required
The identifier half of the credentials Wings uses to validate requests from the Panel. Written by wings configure.
token Required
The secret half of the credentials Wings uses to validate requests from the Panel. Must be kept secret. Written by wings configure.
API Settings
api.host Optional
The IP address Wings binds its internal API to. Alternatively, a Unix socket path can be specified here.
Default: "0.0.0.0"
api.port Optional
The port used by the Wings internal API.
Default: 8080
api.ssl.enabled Optional
Determines whether HTTPS is enabled for the Wings API to ensure encrypted communication.
Default: false
api.ssl.ktls_enabled Optional
Whether to hand HTTPS connections off to the kernel's TLS implementation (kTLS) once the handshake completes, so the kernel encrypts and decrypts records instead of userspace. This mainly speeds up large file transfers and backup downloads. Linux only, and it requires the tls kernel module; Wings probes for kernel support on boot, warns once and stays on userspace TLS if the kernel cannot do it, and falls back per connection when the negotiated cipher suite isn't kTLS compatible. Has no effect unless api.ssl.enabled is true.
Default: false
api.ssl.cert Required for SSL
The absolute filesystem path to the SSL certificate file used for API encryption.
api.ssl.key Required for SSL
The absolute filesystem path to the SSL private key file corresponding to the certificate.
api.redirects Optional
Custom HTTP redirects for the API server (e.g. / → Panel URL).
Default: {}
api.disable_openapi_docs Optional
Controls the availability of the /openapi.json endpoint.
Default: false
api.disable_remote_download Optional
Whether to prevent servers from downloading files directly through remote URLs via the file manager or API.
Default: false
api.remote_download_blocked_cidrs Optional
A security list of CIDR ranges blocked for remote downloads to prevent SSRF (Server-Side Request Forgery) attacks.
Default:
remote_download_blocked_cidrs:
- 0.0.0.0/8
- 127.0.0.0/8
- 10.0.0.0/8
- 100.64.0.0/10
- 172.16.0.0/12
- 192.168.0.0/16
- 169.254.0.0/16
- 192.0.0.0/24
- 198.18.0.0/15
- 224.0.0.0/4
- 240.0.0.0/4
- '::'
- '::1'
- fe80::/10
- fc00::/7
- 2002::/16
- ff00::/8api.disable_directory_size Optional
Whether to disable the calculation of total directory sizes in the file manager.
Default: false
api.directory_entry_limit Optional
The maximum number of files/folders returned in a single /list-directory API call (0 = unlimited).
Default: 10000
api.send_offline_server_logs Optional
When enabled, Wings will transmit cached logs from an offline server immediately upon a websocket connection. This only works when containers are not removed on stop.
Default: false
api.file_search_threads Optional
The number of concurrent worker threads Wings spawns to crawl and scan through server files during a search request.
Default: 4
api.file_search_context.max_matches Optional
The largest number of context blocks per file a search request may ask for. A request above this limit (or asking for 0) is rejected outright rather than trimmed, so raising it lets clients pull more of each file into a single response.
Default: 100
api.file_search_context.max_response_size Optional
The total size (in bytes) of preview context Wings will return across a whole search response. Context blocks are added until the budget is spent; files past it are still listed as matches but come back without preview content and are flagged as truncated. This is the effective ceiling on how large a preview-enabled search response can get.
Default: 8388608
api.file_copy_threads Optional
The number of concurrent worker threads allocated for duplicating files and directories within the file manager. Set to 0 to use every available core.
Default: 4
api.file_delete_threads Optional
The number of concurrent worker threads used to walk and remove a directory tree. Applies to deleting a directory from the file manager and to wiping a server's volume when it is deleted or reinstalled. Set to 0 to use every available core.
Default: 2
api.file_decompression_threads Optional
The number of threads used for extracting archives. Applies to .tar.xz, .tar.lz, .zip, .ddup, .7z. Set to 0 to use every available core.
Default: 4
api.file_compression_threads Optional
The number of threads used for creating archives. Applies to .tar.xz, .tar.lz, .zip, .ddup, .7z. Set to 0 to use every available core.
Default: 2
api.file_fingerprint_threads Optional
The number of files Wings fingerprints in parallel for one request, for checksums from the file manager and the CurseForge hashes mod tooling asks for. Set to 0 to use every available core.
Default: 4
api.upload_limit Optional
The maximum file size in MiB that can be uploaded through the web-based file manager. 0 means no limit, which is the default from Wings 1.2.6; earlier versions defaulted to 100, which only affected enrolled or hand-written configs, since configs generated by the Panel always set this key (to 0 since Panel 1.1.1). SFTP uploads are not affected.
Default: 0
api.max_jwt_uses Optional
The number of times a single JWT can be used for a download or backup before it is invalidated. This provides a security layer to prevent the reuse of temporary access tokens for file and backup downloads.
Default: 5
api.request_log_limit Optional
The number of HTTP requests Wings writes a log line for each second, which keeps a busy node from drowning its own log. Once the budget for a second is spent the remaining requests are counted rather than logged, and the count is reported as a suppressed N http request log lines (api.request_log_limit = 250) line the next time a request gets through; if traffic stops, the summary waits until it resumes. The budget covers the whole process, not each route or client. Set to 0 to log every request.
Default: 250
api.trusted_proxies Optional
A list of trusted IP addresses from proxy servers (like Cloudflare, NGINX, or a Load Balancer) that Wings uses to resolve the actual IP address of a user using the X-Forwarded-For or X-Real-IP header.
Default: []
Schedule Steps
These options govern the HTTP Request step that server schedules can run. The step sends a request to an arbitrary URL from the node, optionally storing the response status and body into schedule variables.
api.schedule.steps.http_request.enabled Optional
Whether servers on this node are allowed to run the HTTP Request schedule step at all. When disabled, any schedule reaching such a step fails with an error instead of sending the request.
Default: true
api.schedule.steps.http_request.requests Optional
The number of HTTP Request steps a single server may execute per rate limit window. Once the limit is hit, further requests fail until the window rolls over.
Default: 5
api.schedule.steps.http_request.window_seconds Optional
The length (in seconds) of the rate limit window that api.schedule.steps.http_request.requests is counted against. The window is per server and restarts once it elapses.
Default: 60
api.schedule.steps.http_request.max_response_size Optional
The maximum size (in bytes) of a response body captured by the step. Only relevant when the step stores the body into a schedule variable; anything past this limit is truncated. This should be kept at or below the 16 KiB schedule variable size limit, since a captured body larger than a variable may hold would fail the step outright.
Default: 16384
api.schedule.steps.http_request.blocked_cidrs Optional
A security list of CIDR ranges that HTTP Request steps may not connect to, preventing SSRF (Server-Side Request Forgery) attacks against services reachable from the node. Enforced both on the URL host and on every address DNS resolves to, so a public hostname pointing at a private address is blocked as well.
Default:
blocked_cidrs:
- 0.0.0.0/8
- 127.0.0.0/8
- 10.0.0.0/8
- 100.64.0.0/10
- 172.16.0.0/12
- 192.168.0.0/16
- 169.254.0.0/16
- 192.0.0.0/24
- 198.18.0.0/15
- 224.0.0.0/4
- 240.0.0.0/4
- '::'
- '::1'
- fe80::/10
- fc00::/7
- 2002::/16
- ff00::/8System Configuration
Path placeholders
data, diffs_directory, vmount_directory, log_directory, archive_directory, backup_directory and tmp_directory accept the {root_directory} placeholder in their value. It's substituted with the configured system.root_directory every time the path is used, so these default to living under root_directory and move together if you repoint it. This is also how a freshly generated config.yml writes these values: literally as {root_directory}/..., not pre-resolved, so editing root_directory alone is enough to relocate everything else that still uses the placeholder. log_directory defaults to a fixed, independent path on Unix; see its entry below.
system.root_directory Optional
This is the root directory where Wings stores its own persistent data (mainly state of servers so it can restore them on restart).
Default: /var/lib/calagopus-wings (Windows: C:\ProgramData\Calagopus-Wings)
system.log_directory Optional
This is the directory where Wings stores its logs.
Default: /var/log/calagopus-wings (Windows: "{root_directory}\\logs")
INFO
Unlike the other directories on this page, log_directory defaults to a fixed path on Unix and does not move with root_directory. On Windows, it defaults to {root_directory}\logs and does follow it.
system.data Optional
This is the directory where Wings stores server data. This is the directory that gets bind-mounted to server containers and is where all server files are stored.
Default: "{root_directory}/volumes" (Windows: "{root_directory}\\volumes")
system.diffs_directory Optional
This is the directory where Wings stores the per-server SQLite databases used by file history to track diffs/revisions of edited files.
Default: "{root_directory}/diffs" (Windows: "{root_directory}\\diffs")
system.vmount_directory Optional
This is the directory where Wings stores virtual mounts for servers. Currently mainly used for spoofing hardware UUIDs for containers. This directory should not be located on a tmpfs (temporary filesystem).
Default: "{root_directory}/vmounts" (Windows: "{root_directory}\\vmounts")
system.archive_directory Optional
This is the directory where Wings stores server archives. This is 100% unused in current code and is simply there for compatibility with Pterodactyl's codebase; it may be used in the future.
Default: "{root_directory}/archives" (Windows: "{root_directory}\\archives")
system.backup_directory Optional
This is the directory where Wings stores server backups. This applies to backups using the Wings backup driver; btrfs and zfs backups also use this directory for snapshots.
Default: "{root_directory}/backups" (Windows: "{root_directory}\\backups")
system.tmp_directory Optional
This is the directory where Wings stores temporary files, such as the staging directories of installation scripts and binaries it extracts for its own use. Wings empties it on every start, except for the staging directories of installations it is about to resume.
Default: "{root_directory}/tmp" (Windows: "{root_directory}\\tmp")
Moved from /tmp
Older versions defaulted to /tmp/calagopus-wings. When Wings runs in a container that path is a bind mount, and a host cleaner deleting it left the mount stale, which broke every installation until the container was recreated. A config that still holds /tmp/calagopus-wings or /tmp/pterodactyl is rewritten to {root_directory}/tmp on start, with a warning that the old directory can be removed. If you run Wings with Docker Compose, the separate /tmp/calagopus-wings volume is no longer needed.
system.username Optional
The operating system user account that the Wings process runs under on the host. In a container, Wings takes it from WINGS_USERNAME instead.
Default: calagopus
system.timezone Optional
The timezone passed into server containers. Generated from TZ, then the first line of /etc/timezone, then the current local UTC offset. The example uses +00:00; the generated value depends on the host. A TZ variable on the server takes precedence, then a per-server timezone set in the Panel.
system.user.rootless.enabled Optional
Enables rootless container execution, allowing Wings to run containers without requiring root privileges on the host. When enabled, Wings takes system.username, system.user.uid and system.user.gid from the user it runs as and derives docker.userns_mode from the container UID/GID below.
Default: false
system.user.rootless.container_uid Optional
The UID the server process runs as inside rootless containers. Left at 0 the server runs as container root, which the default rootless mapping already points at the user running Wings; setting it to that user's own UID works too, since Wings derives a matching docker.userns_mode. Unlike the other user settings, this one is never filled in automatically.
Default: 0
system.user.rootless.container_gid Optional
The GID the server process runs as inside rootless containers. Follows the same rules as system.user.rootless.container_uid.
Default: 0
system.user.uid Optional
The User ID (UID) on the host system that Wings uses when managing server files. Wings sets this on startup from system.username, or from WINGS_UID in a container (988 if unset), so you do not set it yourself.
system.user.gid Optional
The Group ID (GID) on the host system that Wings uses when managing server files. Wings sets this on startup from system.username, or from WINGS_GID in a container (988 if unset), so you do not set it yourself.
system.passwd.enabled Optional Unix only
Whether to enable dynamic generation of /etc/passwd files inside containers to ensure proper username resolution.
Default: false
system.passwd.directory Optional Unix only
The absolute filesystem path where Wings generates and stores the dynamic passwd files.
Default: /run/calagopus-wings/etc
system.machine_id.enabled Optional Unix only
Controls whether a unique, generated machine-id file should be mounted into each server container.
Default: true
system.disk_check_concurrency Optional
The number of concurrent allowed disk scans Wings can perform across all servers. This limits the number of simultaneous disk usage checks to prevent excessive background resource consumption on large nodes.
Default: 2
system.disk_check_interval Optional
Defines how often (in seconds) Wings performs incremental disk usage checks using inotify. These checks are lightweight and rely on filesystem events rather than scanning the entire disk.
Default: 150
system.full_disk_check_every Optional
Number of inotify disk check intervals before performing a full disk scan. Periodic full scans prevent desync between the OS and Wings (e.g. 150s × 4 = 600s / 10 min).
Default: 4
system.disk_check_use_inotify Optional
Uses inotify for selective scanning to reduce scanning overhead of large servers. When disabled, Wings will perform a full disk scan every time instead of relying on inotify events. Disabling this can lead to increased CPU and disk usage, especially on servers with large file counts, but may be necessary in environments where inotify is unreliable or unavailable.
Default: true
system.disk_limiter_mode Optional
INFO
Switching between drivers may require additional manual work. Enabling the quota driver requires specific filesystem support (like prjquota on XFS or ext4) and manual mounting configurations on the host machine. If not configured correctly at the OS level, Wings will fail to start or manage disk limits.
The backend driver used to enforce storage quotas on servers. Available Options:
none, btrfs_subvolume, zfs_dataset, xfs_quota or the experimental fuse_quota
Default: none
system.activity_send_interval Optional
The amount of time (in seconds) that elapses between sending aggregated server activity to the Panel. Wings collects activity over this period and sends it in a single batch.
Default: 60
system.activity_send_count Optional
The number of activity events to send per batch to the Panel. This limits how many collected events are transmitted during each interval.
Default: 100
system.check_permissions_on_boot Optional
Whether to check and correct file permissions for a server whenever its process is booted. This can cause boot delays if the server has a large amount of files.
Default: true
system.check_permissions_on_boot_threads Optional
The number of concurrent threads used to verify and correct file permissions (chown) during the server startup process.
Default: 4
system.websocket_log_count Optional
The number of lines to send when a user connects to the server websocket. This provides the initial "backlog" of console history visible in the Panel.
Default: 150
system.tcp_congestion_control Optional
The TCP congestion control algorithm applied to the sockets Wings owns: the API listener, the SFTP listener, and the outgoing connections used for server transfers and S3 backup uploads (those are routed through a loopback proxy so the algorithm applies to them as well). Linux only, and the algorithm has to be available to the kernel: Wings looks it up in /proc/sys/net/ipv4/tcp_available_congestion_control, tries modprobe tcp_<algorithm> once if it is missing, and keeps the system default with a warning if it still is not there. Set to an empty string to leave congestion control alone entirely.
Default: bbr
SFTP Configuration
system.sftp.enabled Optional
Whether to enable the integrated SFTP (SSH) server.
Default: true
system.sftp.bind_address Optional
The IP address that the internal SFTP/SSH server binds to.
Default: "0.0.0.0"
system.sftp.bind_port Optional
The port that the internal SFTP/SSH server binds to for incoming connections.
Default: 2022
system.sftp.read_only Optional
Whether the SFTP server should operate in read-only mode. If enabled, users can view and download files, but cannot upload, delete, or modify any content.
Default: false
system.sftp.key_algorithm Optional
The cryptographic algorithm used for generating the SSH host key.
Default: ssh-ed25519
system.sftp.disable_password_auth Optional
If enabled, only SSH key authentication is permitted for SFTP/SSH.
Default: false
system.sftp.directory_entry_limit Optional
The maximum number of files and folders returned in a single directory listing. This prevents the SFTP server from hanging when opening folders with massive amounts of data.
Default: 20000
system.sftp.directory_entry_send_amount Optional
The number of directory entries to send in each response chunk to the SFTP client.
Default: 500
system.sftp.limits.authentication_password_attempts Optional
The maximum number of failed password attempts allowed within the cooldown window before the connection is dropped.
Default: 3
system.sftp.limits.authentication_pubkey_attempts Optional
The maximum number of failed public key authentication attempts allowed within the cooldown window before the connection is dropped.
Default: 20
system.sftp.limits.authentication_cooldown Optional
Cooldown period in seconds once attempts are exceeded. This is a sliding window based on the most recent attempt. (3 failed attempts in 1min = 60s wait time from the last attempt)
Default: 60
system.sftp.limits.max_connections_per_user Optional
The maximum number of simultaneous SFTP connections allowed per user account. This prevents a single user from opening too many connections and overwhelming the server.
Default: 10
system.sftp.limits.max_channels_per_connection Optional
The maximum number of concurrent channels (e.g., SFTP sessions, shell sessions) allowed within a single SSH connection. This limits the resources consumed by a single connection.
Default: 10
system.sftp.limits.max_handles_per_channel Optional
The maximum number of open file handles allowed per channel in the SFTP server. This prevents resource exhaustion from too many open files in a single session.
Default: 32
system.sftp.limits.max_handles_total Optional
The maximum total number of open file handles across all channels and connections in the SFTP server. This is a global limit to prevent overall resource exhaustion.
Default: 1024
system.sftp.shell.enabled Optional
Determines whether to allow server management and command-line access via the Wings remote shell over SSH.
Default: true
system.sftp.shell.cli.name Optional
The name used for the internal CLI tool when accessing a server via the remote shell. This is the command users type (e.g., .wings help) to interact with the Wings shell helper.
Default: .wings
system.sftp.activity.log_logins Optional
Whether successful SFTP logins are recorded and displayed in the server's activity log.
Default: false
system.sftp.activity.log_file_reads Optional
Whether reading or downloading files via SFTP is recorded in the server's activity log.
Default: false
Crash Detection
system.crash_detection.enabled Optional
Enables or disables the automatic crash detection system for all servers on the node.
Default: true
system.crash_detection.detect_clean_exit_as_crash Optional
Whether to treat a "clean" exit (an exit code of 0) as a server crash.
Default: true
system.crash_detection.timeout Optional
The amount of time in seconds, that Wings waits after a server process stops before determining it has crashed and attempting a restart.
Default: 60
File History Configuration
system.file_history.enabled Optional
Enables or disables the file history tracking system. When enabled, Wings records a diff-based changelog of edits made to server files through the file manager and SFTP, allowing users to view and restore previous versions.
Default: true
system.file_history.zstd_level Optional
The Zstandard compression level used when storing snapshots and delta entries in the history database. Higher values produce smaller stored history at the cost of more CPU time. Valid range is 1–22.
Default: 9
INFO
Wings 1.2.8 lowered the default from 19 to 9. Wings writes its defaults into config.yml, so an existing node keeps 19 until you change it there.
system.file_history.anchor_interval Optional
The number of delta (diff) entries written in a chain before Wings stores a full snapshot (anchor) instead. A lower value creates anchors more frequently, making history reconstruction faster at the cost of more disk space.
Default: 4
system.file_history.keep_chains Optional
The number of diff chains to retain per file. Once a new chain is started (after an anchor), older chains beyond this count are pruned. Increasing this retains more history depth.
Default: 5
system.file_history.file_size_cap Optional
The maximum size (in bytes) of file content that Wings will read and track through the HTTP file manager. File writes whose pre-write or post-write content exceeds this size are silently skipped and not recorded in history.
Default: 1048576
system.file_history.per_file_disk_budget Optional
The maximum amount of disk space (in bytes) that the history database may use for a single file. When exceeded, Wings drops the oldest diff chains for that file until the budget is met.
Default: 5242880
system.file_history.per_server_disk_budget Optional
The maximum total disk space (in bytes) that the history database may use across all files for a single server. When exceeded, Wings drops the globally oldest diff chains until the budget is met.
Default: 209715200
system.file_history.maintenance_interval Optional
The interval (in seconds) between background maintenance runs that clean up stale history entries and enforce disk budgets.
Default: 3600
Crash History Configuration
system.crash_history.enabled Optional
INFO
Added in Wings 1.2.10.
Enables or disables crash history. When enabled, Wings stores the exit code, whether the server was killed for running out of memory, and the last lines of console output every time crash detection counts a stop as a crash. Records are kept in crash_history.db inside system.root_directory, so the Panel can list a server's past crashes and show the console output that led up to each one. When disabled, nothing is recorded, requests to list or read crashes are refused, and old records are no longer pruned. Data already stored stays in the database file.
Default: true
system.crash_history.lines Optional
How many lines of console output Wings keeps per crash. 0 stores the crash without any console output.
Default: 2000
system.crash_history.record_size_cap Optional
The maximum size (in bytes) of a crash's console output before compression. When the lines exceed it, Wings drops the oldest ones first and marks the crash as truncated. The newest line is always kept, even if it is larger on its own. At most 16777216 (16 MiB) is allowed, otherwise Wings refuses to load the configuration.
Default: 524288
system.crash_history.zstd_level Optional
The Zstandard compression level used for the stored console output. Higher values produce smaller records at the cost of more CPU time when a crash is stored.
Default: 3
system.crash_history.max_records Optional
The maximum number of crashes kept per server. When a new crash goes over it, the oldest records are dropped. 0 removes the limit. The server's most recent crash is always kept.
Default: 10
system.crash_history.max_age Optional
How long (in seconds) a crash record is kept before it is deleted. The default is 30 days. 0 keeps records until another limit removes them.
Default: 2592000
system.crash_history.per_server_disk_budget Optional
The maximum disk space (in bytes, after compression) the crash records of a single server may use. When exceeded, Wings drops the oldest records until the budget is met, but always keeps the server's most recent crash. 0 removes the limit.
Default: 2097152
INFO
All three limits are applied whenever a crash is stored and once an hour in the background. The hourly run also removes the records of servers that are no longer on the node.
system.crash_history.capture_timeout Optional
How long (in seconds) Wings waits to read the console output of a crash. If reading takes longer, the crash is stored with the lines read so far. The limit covers only reading the lines: compressing the log and writing it to the database come after it and have no limit of their own. Wings waits for all of this before it logs the crash activity, runs crash schedules, prints the crash message to the console and decides on the automatic restart, so a slow disk can delay those by more than this value.
Default: 5
Resource History Configuration
system.resource_history.enabled Optional
INFO
Added in Wings 1.2.9.
Enables or disables resource history. When enabled, Wings samples every server's power state, CPU, memory, disk and network usage once a second and stores the aggregated values in resource_history.db inside system.root_directory, so the Panel can chart a server's usage over time. When disabled, nothing is recorded and history requests for the node's servers are refused. Data already stored stays in the database file.
Default: true
system.resource_history.flush_interval Optional
How often (in seconds) Wings writes the samples it has collected in memory to the history database. A lower value loses less history if Wings stops unexpectedly, at the cost of more frequent disk writes.
Default: 10
system.resource_history.tiers Optional
The resolutions history is kept at. Each tier stores one bucket every step seconds and drops buckets older than retention seconds; a retention of 0 keeps them forever. With the defaults, the last hour is kept per second, the last week per 10 seconds, the last year per minute, and everything older per 10 minutes. A history request is answered from the coarsest tier whose step still fits within one chart point and whose data reaches back to the start of the requested range. Since Wings 1.2.10, when no such tier has data in the range, for example a short window further back than the finest tiers keep, Wings answers from a coarser tier that does and spreads each of its buckets over the chart points it covers. Older versions returned an empty chart there.
At most 8 tiers are allowed, every step must be at least 1 and unique, and retention must be 0 or at least the tier's step, otherwise Wings refuses to load the configuration. An empty list stops recording, but unlike enabled: false, history requests are still answered, with no data, and the Panel shows No data recorded in this range.
A tier added later is filled from the existing finer tiers whose step divides its own. A removed tier stops being written, but its data is kept and pruned under its last retention until it runs empty.
Default:
tiers:
- step: 1
retention: 3600
- step: 10
retention: 604800
- step: 60
retention: 31536000
- step: 600
retention: 0File Collaboration Configuration
system.file_collaboration.enabled Optional
Enables or disables the live file collaboration system. When enabled, multiple users can open and edit the same server file simultaneously through the file manager, seeing each other's changes in real time.
Default: true
system.file_collaboration.file_size_cap Optional
The maximum size (in bytes) of a file that can be opened for collaborative editing. Files larger than this cannot be opened in a collaborative session.
Default: 1048576
system.file_collaboration.max_sessions_per_server Optional
The maximum number of concurrent collaborative editing sessions (distinct open files) allowed per server.
Default: 16
system.file_collaboration.max_sessions_per_connection Optional
The maximum number of concurrent collaborative editing sessions a single websocket connection may subscribe to at once.
Default: 8
system.file_collaboration.max_editors_per_session Optional
The maximum number of editors (participants actively editing) allowed to join a single collaborative editing session at once.
Default: 32
system.file_collaboration.max_cursors_per_connection Optional
The maximum number of remote cursors a single websocket connection will track across its subscribed collaborative sessions.
Default: 64
system.file_collaboration.session_grace_period Optional
The amount of time (in seconds) Wings keeps a collaborative session alive after the last participant leaves before tearing it down. This allows a user to briefly disconnect and rejoin without losing the session state.
Default: 30
Websocket Configuration
system.websocket.max_message_size Optional
The maximum size (in bytes) of a single websocket message Wings accepts on a server console connection. A larger message closes the connection instead of being processed.
Default: 1048576
system.websocket.max_frame_size Optional
The maximum size (in bytes) of a single websocket frame. A message may be split across multiple frames, so this bounds an individual frame rather than the whole message.
Default: 1048576
system.websocket.read_buffer_size Optional
The size (in bytes) of the read buffer allocated for each websocket connection. Raising it lowers the number of reads on busy consoles at the cost of memory per open connection.
Default: 8192
system.websocket.authentication_timeout Optional
The amount of time (in seconds) a websocket connection may stay unauthenticated before Wings closes it. It is checked on the same 30 second interval as the connection ping, so the close lands on the first ping past the timeout (0 = unlimited).
Default: 60
system.websocket.unauthenticated_connections_per_ip Optional
The number of websocket connections a single IP address may hold open before sending a valid token. The slot is released the moment a connection authenticates, so this only bounds connections sitting in the pre-authentication state. Connections past the limit are rejected with 429 Too Many Requests (0 = unlimited).
Default: 32
INFO
Connections are counted against the client IP Wings resolved, so api.trusted_proxies has to be correct when Wings sits behind a reverse proxy. Without it every connection is attributed to the proxy and a single busy panel exhausts the limit for everyone.
system.websocket.max_connections_total Optional
The maximum number of websocket connections Wings holds open across all servers at once, authenticated or not. Connections past the limit are rejected with 429 Too Many Requests (0 = unlimited).
Default: 0
Backups Configuration
system.backups.write_limit Optional
The maximum disk write speed (in MiB/s) for creating backups. This prevents restoration processes from saturating the disk I/O and slowing down the rest of the node (0 = unlimited).
Default: 0
system.backups.read_limit Optional
The maximum disk read speed (in MiB/s) when restoring backups. Prevents backups from slowing down the rest of the node (0 = unlimited).
Default: 0
system.backups.compression_level Optional
Defines the CPU vs. compression ratio. Higher compression saves disk space but uses more CPU (best_speed = fastest, best_compression = smallest file).
Options: best_speed, good_speed, good_compression, best_compression
Default: best_speed
system.backups.mounting.enabled Optional
Allows users to browse and interact with backup contents directly via the File Manager without needing to download them first.
Default: true
system.backups.mounting.path Optional
The path prefix used for the virtual backup mount (e.g., .backups/<uuid>).
Default: .backups
system.backups.wings.create_threads Optional
The number of CPU threads used when compressing local backups. This applies specifically to .tar.gz, .tar.xz, .tar.lz, .tar.zst, and .7z.
Default: 4
system.backups.wings.restore_threads Optional
The number of CPU threads used for extracting local backup archives. This applies specifically to .tar.xz, .tar.lz, .zip, .ddup and .7z.
Default: 4
system.backups.wings.archive_format Optional
The compression format used for local backups.
Options: tar, tar_gz, tar_xz, tar_lzip, tar_bz2, tar_lz4, tar_zstd, zip, seven_zip
Default: tar_gz
system.backups.s3.create_threads Optional
The number of CPU threads used when compressing backups for S3 storage. This applies specifically to .tar.gz, .tar.xz, .tar.lz and .tar.zst.
Default: 4
system.backups.s3.streaming Optional
Whether server-file S3 backups try the streaming endpoint before falling back to a buffered upload. Set to false to skip the probe and use buffered uploads directly, for example with a Panel that does not support that endpoint. Database dumps use a separate streaming path and are unaffected.
Default: true
system.backups.s3.part_upload_timeout Optional
The maximum time (in seconds) to wait for a single part of a multipart upload.
Default: 7200
INFO
Before Wings 1.2.9 this was also the total time limit for downloading an S3 backup to restore a server backup or a database backup, so a restore that took longer than this failed. Downloads now have a 30-second connect timeout and no total limit.
system.backups.s3.retry_limit Optional
The number of retry attempts for each failed upload part.
Default: 10
system.backups.ddup_bak.create_threads Optional
The number of threads used for ddup-bak backup creation.
Default: 4
system.backups.ddup_bak.restore_threads Optional
The number of threads used for restoring ddup-bak backups. Each thread restores one file, so with 4 threads, up to 4 files are restored concurrently.
Default: 4
system.backups.ddup_bak.compression_format Optional
Compression for DdupBak backups: none, deflate, gzip, brotli, or zstd. New configurations default to zstd; an existing explicit value such as deflate is kept.
Options: none, deflate, gzip, brotli, zstd
Default: zstd
system.backups.restic.repository Optional
INFO
On Calagopus, restic is normally configured through a backup configuration in the panel. If the file at password_file exists, Wings uses these local options instead, for every restic backup on the node.
The Restic repository path used for backups. This must already be initialized and can be overridden by the panel.
Default: "{root_directory}/backups/restic" (Windows: "{root_directory}\\backups\\restic")
system.backups.restic.password_file Optional
The local path to the file containing the Restic repository password used for authentication. This can be overridden by the panel.
Default: "{root_directory}/backups/restic_password" (Windows: "{root_directory}\\backups\\restic_password")
system.backups.restic.retry_lock_seconds Optional
The amount of time (in seconds) Wings will wait if the Restic repository is locked by another process before failing the backup task. This can be overridden by the panel.
Default: 60
system.backups.restic.environment Optional
The environment variables passed to the restic process for authentication and configuration. Every variable except PATH is passed through. Panel configuration patches cannot change this key.
Default: {}
system.backups.kopia.create_threads Optional
INFO
The system.backups.kopia options were added in Wings 1.2.9.
The number of files Kopia uploads in parallel when creating a server backup, passed to kopia snapshot create as --parallel. 0 leaves the flag off and uses Kopia's own default.
Default: 0
system.backups.kopia.restore_threads Optional
The number of files Kopia restores in parallel when a backup is restored onto a server, passed to kopia restore as --parallel.
Default: 8
system.backups.kopia.retry_limit Optional
How many times Wings retries a Kopia snapshot or ignore-policy change that failed with a transient error (policy not found or connection refused). The wait before retry n is n² seconds plus up to 30% jitter. Set to 0 to fail on the first error.
Default: 3
system.backups.btrfs.restore_threads Optional
The number of threads used for restoring Btrfs snapshots. Each thread processes one file, so with 4 threads, up to 4 files are restored concurrently.
Default: 4
system.backups.btrfs.create_read_only Optional
Whether to create read-only snapshots to prevent data modification after the backup is taken.
Default: true
system.backups.zfs.restore_threads Optional
The number of threads used for restoring ZFS snapshots. Each thread processes one file, so with 4 threads, up to 4 files are restored concurrently.
Default: 4
system.backups.pbs.create_threads Optional
The number of threads used when creating Proxmox Backup Server (PBS) backups. Each thread processes one file concurrently while the backup is being uploaded.
Default: 4
system.backups.pbs.download_concurrency Optional
The number of chunks downloaded concurrently when restoring a Proxmox Backup Server (PBS) backup.
Default: 4
Transfers
system.transfers.download_limit Optional
The download rate limit for transfers in MiB/s (0 = unlimited).
Default: 0
Docker Configuration
docker.socket Optional
The path to the Docker daemon socket or HTTP address.
Default: /var/run/docker.sock (Windows: //./pipe/docker_engine)
docker.server_name_in_container_name Optional
Whether to include the server's name within the Docker container name for easier identification in tools like docker ps.
Default: false
docker.delete_container_on_stop Optional
When enabled, containers are deleted as soon as a server stops, is killed, or crashes. This significantly reduces long-term CPU/resource overhead.
Default: true
docker.network.interface Optional
The specific IP interface used for the Docker network bridge.
Default: "172.18.0.1"
docker.network.disable_interface_binding Optional
Whether to disable binding containers to a specific network interface on the host.
Default: false
docker.network.dns Optional
The list of DNS servers used by containers for name resolution.
Default:
dns:
- '1.1.1.1'
- '1.0.0.1'docker.network.dns_options Optional
Resolver options (as used in /etc/resolv.conf's options line) applied to containers alongside docker.network.dns.
Default:
dns_options:
- ndots:0
- timeout:2
- attempts:3
- single-request-reopendocker.network.name Optional
The name of the Docker network used by Wings to manage container communication.
Default: calagopus_nw
docker.network.ispn Optional
The flag that determines if the Docker network used by Wings is "internal", meaning it has no access to the external internet.
Default: false
docker.network.driver Optional
The Docker network driver used for the container network (e.g. bridge).
Default: bridge
docker.network.mode Optional
The network mode containers are attached to, passed to the Docker daemon as-is. This should match docker.network.name; if name is changed without changing mode, Wings warns on startup that containers are being attached to a network that does not exist. Also accepted under the legacy key network_mode.
Default: calagopus_nw
docker.network.is_internal Optional
Whether to mark the network as internal-only, restricting containers from accessing the outside internet.
Default: false
docker.network.enable_icc Optional
Enables Inter-Container Communication, allowing containers on the same network to talk to one another.
Default: true
docker.network.network_mtu Optional
Sets the Maximum Transmission Unit (MTU) size for the container network.
Default: 1500
docker.network.interfaces.v4.enabled Optional
Whether to enable IPv4 on the Docker network bridge. At least one of docker.network.interfaces.v4.enabled and docker.network.interfaces.v6.enabled must stay true - Wings refuses to create the network if both are disabled.
Default: true
docker.network.interfaces.v4.subnet Optional
The IPv4 subnet range used by the Docker network.
Default: 172.18.0.0/16
docker.network.interfaces.v4.gateway Optional
The IPv4 gateway address for the Docker network. This will automatically be incremented if the address is already in use by another network on the host.
Default: "172.18.0.1"
docker.network.interfaces.v6.enabled Optional
Whether to enable IPv6 on the Docker network bridge. At least one of docker.network.interfaces.v4.enabled and docker.network.interfaces.v6.enabled must stay true - Wings refuses to create the network if both are disabled.
Default: true
docker.network.interfaces.v6.subnet Optional
The IPv6 subnet range used by the Docker network.
Default: fdba:17c8:6c94::/64
docker.network.interfaces.v6.gateway Optional
The IPv6 gateway address for the Docker network.
Default: fdba:17c8:6c94::1011
docker.firewall.backend Optional
Which backend Wings uses to apply per-server firewall rules on the host.
auto: pick a backend on boot. Wings prefersnftables, falls back toiptables, and uses the helper container when it runs inside a container that has its own network namespace.nftables: runnftdirectly on the host.iptables: runiptablesdirectly on the host.container: runnftthrough a helper container started from the Wings image, namedcalagopus-wings-firewall-followed by the first 12 characters of the ID of the Wings container (calagopus-wings-firewallbefore Wings 1.2.8). Use this when Wings runs as a container without host networking, where rules applied in its own network namespace would never see server traffic.disabled: never apply rules.
Default: auto
WARNING
Server firewalls are Linux only, and are not supported with a rootless container engine, because published port traffic does not traverse the host netfilter forward path there.
When no backend ends up usable (an unsupported platform, a rootless engine, neither nft nor iptables present, or a helper container that fails to start), a server that has firewall rules configured refuses to start rather than running unprotected. Set this to disabled to start such servers anyway, in which case Wings logs a warning per server and leaves its rules unapplied.
The container backend runs nft out of the Wings image itself, so that image has to carry the binary. The official Wings and All-in-One images do; a custom image may not, and Wings then reports that nft is missing from the image the helper container runs.
docker.firewall.source_file_max_entries Optional
The maximum number of entries Wings loads from the source file of a firewall rule. A file holding more than this is rejected as a whole, and the rule keeps the entries it last loaded.
Default: 10000
docker.firewall.source_file_max_bytes Optional
The maximum size (in bytes) of the source file of a firewall rule. A file larger than this is rejected as a whole, and the rule keeps the entries it last loaded.
Default: 1048576
docker.bandwidth.backend Optional
How Wings enforces the per-server upload and download limits set in the Panel. Limits are applied inside each server's network namespace with tbf and fq_codel: upload on the container's interface, download through an ifb device named wings-dl that Wings creates inside the container. They are applied when the server starts and updated live when its limits change, without a restart.
auto:localwhen Wings runs on the host, or in a container that shares the host PID namespace and holdsCAP_NET_ADMINandCAP_SYS_ADMIN. Otherwisecontainer. Withsystem.user.rootless.enabledon, the capabilities are not checked.local: Wings applies the limits itself. Rootful Wings needsCAP_NET_ADMINandCAP_SYS_ADMIN, which it has when it runs as root on the host. Rootless Wings needs user namespaces (/proc/sys/user/max_user_namespacesabove0). Wings in a container without the host PID namespace cannot reach server network namespaces, so limits are unavailable with this backend there.container: Wings starts a helper container, namedcalagopus-wings-bandwidth-followed by the first 12 characters of the ID of the Wings container (calagopus-wings-bandwidthbefore Wings 1.2.8), from its own image with the host PID namespace, no network, andNET_ADMINandSYS_ADMIN, and applies the limits through it. Only works when Wings itself runs as a container on the Docker engine it manages, and not with rootless container engines.disabled: limited servers start without their limits, and Wings logs a warning for each one.
Options: auto, local, container, disabled
Default: auto
WARNING
Bandwidth limits are Linux only. The Wings Docker Compose file shares the host PID namespace (pid: host) since Wings 1.2.6, but the Wings container does not hold CAP_NET_ADMIN or CAP_SYS_ADMIN. Wings 1.2.8 and newer check for those capabilities and auto uses the helper container. On Wings 1.2.6 and 1.2.7, auto picks local there and limits stay unavailable, so set this option to container. Adding cap_add: [NET_ADMIN, SYS_ADMIN] to the wings service gives Wings the same privileges as the helper container instead, and auto then picks local. An older Compose file without pid: host gets the helper container through auto.
Each Wings container gets its own helper, so several Wings containers can share one Docker engine. On startup Wings removes its own old helper, helpers left behind by a Wings container that is gone or no longer running, and the unsuffixed helper older versions created. The firewall helper works the same way.
The Panel shows the reason on the server's limit fields when a node can't apply limits, and refuses to save a non-zero limit there, including when this option is disabled. A limited server needs a bridge network with exactly one interface; host, none and container: network modes are rejected, as is a server container granted NET_ADMIN, NET_RAW or SYS_ADMIN. If limits are unavailable or shaping fails when a limited server starts, the start fails rather than running the server unthrottled. Set this option to disabled to start such servers without their limits.
INFO
This option replaced docker.bandwidth.enabled in Wings 1.2.6. On startup Wings turns enabled: false into backend: disabled, drops the old key from config.yml, and logs migrated docker.bandwidth.enabled to docker.bandwidth.backend.
docker.domainname Optional
The domain name assigned to containers, useful for internal networking resolution.
Default: ""
docker.registries Optional
The Docker registry authentication configurations used for pulling private images, keyed by registry hostname. Each entry needs a username and a password.
Default: {}
docker.registry_image_fetch_cache.enabled Optional
Whether to enable caching of image metadata (e.g., digests, tags) from Docker registries to reduce API calls and speed up repeated server starts.
Default: true
docker.registry_image_fetch_cache.duration Optional
The duration (in seconds) that cached image metadata is considered valid before it is refreshed with a new request to the Docker registry.
Default: 300
docker.registry_image_fetch_cache.background_refresh Optional
Whether a stale image is refreshed in the background instead of holding up the server boot. When enabled and the image already exists on the host, Wings boots the server from the local copy right away and pulls the newer image in a background task, so the update only takes effect on the next start. Images that are not on the host yet are still pulled before the server boots.
Default: false
docker.tmpfs_size Optional
The size (in MiB) of the /tmp directory mounted as a tmpfs in containers.
Default: 100
docker.shm_size Optional
The size (in MiB) of /dev/shm inside containers. 0 leaves Docker's own default (64 MiB) in place. Raise it for games that map large amounts of shared memory.
Default: 0
docker.container_pid_limit Optional
The maximum number of processes (PIDs) allowed to run simultaneously within a single container.
Default: 5120
docker.container_apply_seccomp Optional
Whether to apply a modified seccomp profile with additional syscalls toggled from the panel, this can break on podman.
Default: true
docker.container_apparmor_profile Optional
The name of an AppArmor profile to confine server containers with, passed to Docker as apparmor=<profile>. The profile must already be loaded on the host. Leaving this empty lets Docker apply its own docker-default profile.
Default: ""
docker.container_ulimits Optional
Per-container resource limits, applied to every server container Wings creates. Each entry is a name, a soft limit and a hard limit, matching the --ulimit flag of docker run (-1 means unlimited). An empty list leaves the daemon defaults in place. A nofile hard limit larger than what the host lets Wings raise its own limit to is clamped down to that ceiling, with a warning logged once.
Default: []
INFO
Each entry is a map, so a raised file descriptor limit looks like this:
container_ulimits:
- name: nofile
soft: 65535
hard: 65535docker.container_sysctls Optional
Kernel parameters set inside every server container, matching the --sysctl flag of docker run. Only namespaced sysctls can be set this way; the Docker daemon rejects the container outright for anything else. Entries starting with net. are skipped for containers that share a foreign network namespace (host or container:<id> network modes), since those sysctls belong to the namespace owner.
Default: {}
docker.numa_memory_binding Optional
Whether to bind a container's memory to the NUMA nodes its pinned CPU threads live on, keeping allocations local instead of spread across sockets. Only takes effect on a multi-node host for servers that have CPU pinning set; single-node machines and unpinned servers are unaffected.
Default: true
docker.cpu_period Optional
The CFS scheduling period (in microseconds) used for container CPU limits. A server's CPU limit is turned into a quota of limit% × cpu_period, so a shorter period hands out CPU time in smaller, more frequent slices, at the cost of more scheduler overhead. Values are clamped to the kernel's accepted range of 1000 - 1000000.
Default: 100000
docker.cfs_burst.enabled Optional
Whether to grant containers CFS burst, letting a server bank unused CPU time within a period and spend it on a later spike instead of being throttled. Requires a kernel with CFS burst support (cpu.max.burst on cgroup v2, cpu.cfs_burst_us on v1); where it is unsupported, Wings leaves it alone and warns about it once. Servers without a CPU limit are unaffected, they are not throttled to begin with.
Default: true
docker.cfs_burst.multiple Optional
The fraction of a server's CPU quota that may be banked as burst. 1.0 allows a full extra period's worth of CPU time, 0.5 half of it, 0 disables bursting for the same effect as turning enabled off. The kernel refuses a burst larger than the quota, so values above 1.0 are clamped.
Default: 1.0
docker.startup_boost.enabled Optional
Whether to lift a server's CPU limit while it is booting. With this on, a starting container runs without a CPU quota until it reports as running (or docker.startup_boost.timeout elapses), after which the configured limit and CFS burst are put back. This mainly helps single-threaded boot work like world generation or mod loading. Servers without a CPU limit are unaffected, they are already unthrottled. These are the node-wide defaults and can be overridden by the panel, which may give an individual server its own enabled and timeout to use in place of the values here.
Default: false
docker.startup_boost.timeout Optional
The maximum time (in seconds) a server may stay boosted. Once the server leaves the starting state or this many seconds pass, whichever comes first, its CPU quota is restored.
Default: 120
docker.startup_boost.max_concurrent Optional
The number of servers that may be boosted at the same time on this node. Servers that start while this many boosts are already active simply boot with their normal CPU limit, so a mass restart cannot hand out unlimited CPU to every server at once. Unlike the other options in this block, this one is always taken from the node config, a per-server override from the panel cannot raise it.
Default: 3
docker.runtime_boost.enabled Optional
Whether to temporarily raise a server's CPU quota when it is pinned against its limit while running. Wings watches the per-second CPU samples it already collects for the stats websocket, and once a server has sat at or above docker.runtime_boost.threshold of its limit for docker.runtime_boost.sustained samples in a row it hands out extra quota for docker.runtime_boost.duration seconds before restoring the configured limit. Unlike docker.startup_boost, this applies to a server that is already running, so it covers spikes like a large world save or a burst of players joining rather than boot work. Servers without a CPU limit are unaffected, they are already unthrottled, and a server that is currently startup boosted is never boosted again on top of it. These are the node-wide defaults and can be overridden by the panel, which may give an individual server its own values for every option below except docker.runtime_boost.max_concurrent.
Default: false
docker.runtime_boost.threshold Optional
The share (%) of a server's configured CPU limit that counts as pinned. A server limited to 200% with the default threshold of 90 has to use at least 180% CPU for a sample to count towards a boost.
Default: 90
docker.runtime_boost.sustained Optional
The number of consecutive one second samples a server must spend at or above the threshold before it is boosted, so brief spikes do not trigger one. The streak resets whenever a sample falls below the threshold, the server leaves the running state, or a boost is granted.
Default: 10
docker.runtime_boost.multiple Optional
The multiplier applied to the server's CPU quota while boosted. 2.0 gives it twice its configured limit for the duration of the boost. Values below 1.0 are clamped to 1.0, since a boost never hands out less CPU than the server already has.
Default: 2.0
docker.runtime_boost.duration Optional
How long (in seconds) a boost lasts. Once this elapses the server's configured CPU limit and CFS burst are put back, whether or not it is still pinned.
Default: 60
docker.runtime_boost.cooldown Optional
How long (in seconds) a server has to wait after a boost ends before it may be boosted again, so a permanently overloaded server cannot simply run at its boosted limit forever.
Default: 300
docker.runtime_boost.max_concurrent Optional
The number of servers that may be boosted at the same time on this node. While this many boosts are active, a server that hits the threshold keeps its normal CPU limit and its streak resets, so a node-wide load spike cannot boost every server at once. Unlike the other options in this block, this one is always taken from the node config, a per-server override from the panel cannot raise it.
Default: 3
docker.lxcfs.enabled Optional Unix only
Bind host lxcfs files into server containers so software reading /proc and /sys can see container resource limits. Requires lxcfs to be running on the container host; Wings does not start it itself. Installer containers are unaffected. Restart Wings and then each server after changing this setting. See LXCFS Setup.
Default: false
docker.lxcfs.directory Optional Unix only
The lxcfs mount directory on the container host. An existing distribution service commonly uses /var/lib/lxcfs; wings service-install --lxcfs creates a separate service at /var/lib/calagopus-wings/lxcfs and saves that path when a Wings configuration is loaded. Change this path locally, because configuration patches from the Panel cannot alter it.
Default: /var/lib/lxcfs
docker.installer_limits.timeout Optional
The maximum time (in seconds) allowed for an installation container to run before it is considered failed (0 = no limit).
Default: 1800
docker.installer_limits.memory Optional
The memory limit (in MiB) for installer containers. This will be overwritten with the server's memory limit if it is higher.
Default: 1024
docker.installer_limits.cpu Optional
The CPU limit (%) for installer containers. This will be overwritten with the server's CPU limit if it is higher.
Default: 100
docker.overhead.override Optional
The toggle to enable or disable custom memory overhead multipliers.
Default: false
docker.overhead.default_multiplier Optional
The default multiplier applied to a server's memory limit to account for Docker container overhead.
Default: 1.05
docker.overhead.multipliers Optional
A map of specific memory thresholds to custom multipliers, allowing for granular overhead control based on server size.
Default: {}
docker.userns_mode Optional
The user namespace mode for containers, used to isolate container users from host users for enhanced security. Left empty with system.user.rootless.enabled on, Wings derives keep-id:uid=<container_uid>,gid=<container_gid> from the rootless settings; setting it explicitly opts out of that and is passed through untouched.
Default: ""
docker.mount_options Optional
Extra options appended to every bind mount of server, installer and script runner containers, such as idmap, which together with docker.userns_mode keeps file ownership identical inside and outside the container. Options are passed to the container engine untouched and are engine-specific: rootful Podman supports idmap, while Docker rejects options it does not know and the container then fails to create. Kernel filesystem sources (/dev, /proc, /sys) and lxcfs mounts never get them. Changes apply to containers created afterwards.
Default: []
docker.log_config.type Optional
The Docker logging driver type used to capture and store container output.
Default: local
docker.log_config.config.compress Optional
Whether to enable compression for stored log files to save disk space.
Default: "false"
docker.log_config.config.max-file Optional
The maximum number of log files to retain before the oldest ones are rotated out.
Default: "1"
docker.log_config.config.max-size Optional
The maximum size allowed for a single log file before it is rotated.
Default: 5m
docker.log_config.config.mode Optional
The delivery mode for logs (e.g. non-blocking), determining how Docker handles log data when the buffer is full.
Default: non-blocking
Limits
Per-server caps on long-running file operations. An operation over a limit is refused straight away with 417 Expectation Failed rather than queued, so the user sees the error and can retry once something finishes.
limits.server_concurrent_pulls Optional
The maximum number of remote file pulls (downloads from a URL) one server can run at once. Set to 0 for no limit.
Default: 3
INFO
This replaces api.server_remote_download_limit. A config that still sets the old key is migrated on start and whenever the panel pushes a config, with a warning in the log: its value moves here, except 0, which used to block remote pulls entirely and now turns on api.disable_remote_download instead, since 0 means unlimited here.
limits.server_concurrent_operations Optional
The maximum number of file operations one server can run at once: archiving, extracting, copies (including to other servers), remote pulls and backup exports, whether started from the file manager or a schedule. Pulls count toward this limit as well as their own. Set to 0 for no limit.
Default: 0
Throttles
throttles.enabled Optional
The toggle to enable or disable console output throttling for all containers.
Default: true
throttles.lines Optional
The maximum number of console lines stored in the buffer for each server.
Default: 2000
throttles.line_reset_interval Optional
The interval (in seconds) at which the console line counters are reset.
Default: 100
Private Network
Tundra is the daemon that carries the private network, the encrypted node-to-node tunnel servers use to reach each other without going over the public internet. It runs as a privileged container Wings manages, and it is off by default on every node.
Turning it on here only makes the node capable of it. An administrator still has to put the node on the network from its Private Network tab in the panel. That tab is also where you set the host and UDP port other nodes dial this one on.
WARNING
The private network is Linux only. Rootless Podman carries it, because the daemon runs in the same user namespace that owns the server containers, so it can still bind sockets inside their network namespaces. Rootless Docker cannot: host networking there is RootlessKit's own namespace rather than the host's, so peers never reach the tunnel port. Wings does not check for this, so a rootless Docker node with enabled set still reports itself as supported in the panel.
tundra.enabled Optional
Whether Wings runs the tundra daemon on this node. With this off, servers on the node cannot join the private network, and the panel reports the node as unable to run it.
Default: false
tundra.data_directory Optional
Where the daemon's persistent state lives, including the node's local CA, its identity and the control socket Wings talks to it over.
Default: "{root_directory}/tundra" (Windows: "{root_directory}\\tundra")
tundra.binary Optional
Path to a tundra binary to run instead of the bundled one. Leave empty and Wings extracts the binary from source_image.
Default: ""
tundra.image Optional
The base image the daemon container runs on.
Default: debian:trixie-slim
tundra.source_image Optional
The image the tundra binary is extracted from when binary is empty. Pin this to control which tundra version the node runs.
Default: calagopus/tundra:latest
tundra.metrics_port Optional
The loopback port the daemon serves its metrics on, which is what feeds the node's live peer links in the panel. It is not the port peers connect on; that one is set per node in the panel.
Default: 7101
Remote Configuration
remote Required
The URL of the Panel instance that this Wings node communicates with. Wings refuses to start if it is empty, or does not start with http:// or https://.
remote_headers Optional
Custom HTTP headers that Wings includes in every outgoing HTTP request to the Panel.
Default: {}
remote_query.timeout Optional
The maximum number of retries for critical API requests. This uses an exponential backoff strategy.
Default: 30
remote_query.boot_servers_per_page Optional
The number of servers Wings requests from the Panel API in a single batch during the initial boot sequence.
Default: 50
remote_query.retry_limit Optional
The maximum number of times Wings will attempt to re-send a failed request to the Panel before giving up.
Default: 10
Security / Behaviour Flags
allowed_mounts Optional
A security whitelist defining which specific directories or files on the host system are permitted to be mounted into a server's Docker container.
Default: []
allowed_devices Optional
Host device paths or directories whose devices may be passed into server containers through the Panel Devices feature. Empty by default, so no Panel-defined device mappings are allowed. Sources must resolve to character or block devices within an allowed path; invalid mappings are skipped with a warning. Prefer individual device paths over broad directories. Change this on the Wings host, because the Panel cannot update it. The separate built-in KVM passthrough setting is unaffected.
Default: []
allowed_origins Optional
A list of specific URLs (origins) that are permitted to make cross-origin requests to the Wings API. By default, the URL defined in the remote: setting is the only allowed origin.
Default: []
allow_cors_private_network Optional
Determines whether Wings permits Cross-Origin Resource Sharing (CORS) requests originating from private network addresses.
Default: false
ignore_panel_config_updates Optional
When set to true, Wings will ignore configuration update commands sent by the Panel.
Default: false
Options the panel can never change
Even with panel config updates enabled, a set of paths is stripped out of every patch the panel sends, so change them locally in config.yml or through environment overrides:
- Node identity:
uuid,token,token_id,remote,remote_headers - Paths:
system.root_directory,system.log_directory,system.data,system.diffs_directory,system.vmount_directory,system.archive_directory,system.backup_directory,system.tmp_directory,system.passwd.directory,system.backups.restic.repository,system.backups.restic.password_file,system.backups.restic.environment,system.backups.mounting.path,docker.lxcfs.directory,tundra.data_directory,tundra.binary - Host access:
system.username,system.user,system.passwd,docker.socket,tundra.image,tundra.source_image,allowed_mounts,allowed_devices - Listener and egress:
api.host,api.port,api.ssl,api.trusted_proxies,api.disable_remote_download,api.remote_download_blocked_cidrs,api.schedule.steps.http_request - The flags themselves:
ignore_panel_config_updates,ignore_panel_wings_upgrades
The rest of the patch still applies, the forbidden keys are dropped silently rather than failing the whole update.
ignore_panel_wings_upgrades Optional
When set to true, Wings will ignore remote upgrade commands sent by the Panel.
Default: false
SSL Configuration
INFO
This section is a quick reference. Securing Wings with SSL covers the full setup, including getting a certificate, Docker installs, pointing the Panel at the node and renewal. Replace <domain> with your actual node domain.
Enabling SSL
SSL is disabled by default. To secure Wings' communication, set enabled to true under api.ssl and point cert/key to your certificate files.
If you're using Let's Encrypt, your config should look like this:
api:
host: 0.0.0.0
port: 8080
ssl:
enabled: true
cert: /etc/letsencrypt/live/<domain>/fullchain.pem
key: /etc/letsencrypt/live/<domain>/privkey.pemApplying Changes
After saving config.yml, restart Wings for the new SSL configuration to take effect:
sudo systemctl restart wingsExample Config
The following is an example of a standard generated config.yml for Wings with standard values. A handful of defaults differ between platforms (mainly paths and the Unix-only passwd/machine_id sections), so both are shown below.
Show the example config
debug: false
app_name: Calagopus
uuid: UUID_HERE
token_id: TOKEN_ID_HERE
token: TOKEN_HERE
api:
host: '0.0.0.0'
port: 8080
ssl:
enabled: false
ktls_enabled: false
cert: ''
key: ''
redirects: {}
disable_openapi_docs: false
disable_remote_download: false
remote_download_blocked_cidrs:
- 0.0.0.0/8
- 127.0.0.0/8
- 10.0.0.0/8
- 100.64.0.0/10
- 172.16.0.0/12
- 192.168.0.0/16
- 169.254.0.0/16
- 192.0.0.0/24
- 198.18.0.0/15
- 224.0.0.0/4
- 240.0.0.0/4
- '::'
- '::1'
- fe80::/10
- fc00::/7
- 2002::/16
- ff00::/8
disable_directory_size: false
directory_entry_limit: 10000
send_offline_server_logs: false
file_search_threads: 4
file_search_context:
max_matches: 100
max_response_size: 8388608
file_copy_threads: 4
file_delete_threads: 2
file_decompression_threads: 4
file_compression_threads: 2
file_fingerprint_threads: 4
upload_limit: 0
max_jwt_uses: 5
request_log_limit: 250
trusted_proxies: []
schedule:
steps:
http_request:
enabled: true
requests: 5
window_seconds: 60
max_response_size: 16384
blocked_cidrs:
- 0.0.0.0/8
- 127.0.0.0/8
- 10.0.0.0/8
- 100.64.0.0/10
- 172.16.0.0/12
- 192.168.0.0/16
- 169.254.0.0/16
- 192.0.0.0/24
- 198.18.0.0/15
- 224.0.0.0/4
- 240.0.0.0/4
- '::'
- '::1'
- fe80::/10
- fc00::/7
- 2002::/16
- ff00::/8
system:
root_directory: /var/lib/calagopus-wings
log_directory: /var/log/calagopus-wings
data: '{root_directory}/volumes'
diffs_directory: '{root_directory}/diffs'
vmount_directory: '{root_directory}/vmounts'
archive_directory: '{root_directory}/archives'
backup_directory: '{root_directory}/backups'
tmp_directory: '{root_directory}/tmp'
username: calagopus
timezone: +00:00
user:
rootless:
enabled: false
container_uid: 0
container_gid: 0
uid: 995
gid: 985
passwd:
enabled: false
directory: /run/calagopus-wings/etc
machine_id:
enabled: true
disk_check_concurrency: 2
disk_check_interval: 150
full_disk_check_every: 4
disk_check_use_inotify: true
disk_limiter_mode: none
activity_send_interval: 60
activity_send_count: 100
check_permissions_on_boot: true
check_permissions_on_boot_threads: 4
websocket_log_count: 150
tcp_congestion_control: bbr
sftp:
enabled: true
bind_address: '0.0.0.0'
bind_port: 2022
read_only: false
key_algorithm: ssh-ed25519
disable_password_auth: false
directory_entry_limit: 20000
directory_entry_send_amount: 500
limits:
authentication_password_attempts: 3
authentication_pubkey_attempts: 20
authentication_cooldown: 60
max_connections_per_user: 10
max_channels_per_connection: 10
max_handles_per_channel: 32
max_handles_total: 1024
shell:
enabled: true
cli:
name: .wings
activity:
log_logins: false
log_file_reads: false
crash_detection:
enabled: true
detect_clean_exit_as_crash: true
timeout: 60
file_history:
enabled: true
zstd_level: 9
anchor_interval: 4
keep_chains: 5
file_size_cap: 1048576
per_file_disk_budget: 5242880
per_server_disk_budget: 209715200
maintenance_interval: 3600
crash_history:
enabled: true
lines: 2000
record_size_cap: 524288
zstd_level: 3
max_records: 10
max_age: 2592000
per_server_disk_budget: 2097152
capture_timeout: 5
resource_history:
enabled: true
flush_interval: 10
tiers:
- step: 1
retention: 3600
- step: 10
retention: 604800
- step: 60
retention: 31536000
- step: 600
retention: 0
file_collaboration:
enabled: true
file_size_cap: 1048576
max_sessions_per_server: 16
max_sessions_per_connection: 8
max_editors_per_session: 32
max_cursors_per_connection: 64
session_grace_period: 30
websocket:
max_message_size: 1048576
max_frame_size: 1048576
read_buffer_size: 8192
authentication_timeout: 60
unauthenticated_connections_per_ip: 32
max_connections_total: 0
backups:
write_limit: 0
read_limit: 0
compression_level: best_speed
mounting:
enabled: true
path: .backups
wings:
create_threads: 4
restore_threads: 4
archive_format: tar_gz
s3:
create_threads: 4
streaming: true
part_upload_timeout: 7200
retry_limit: 10
ddup_bak:
create_threads: 4
restore_threads: 4
compression_format: zstd
restic:
repository: '{root_directory}/backups/restic'
password_file: '{root_directory}/backups/restic_password'
retry_lock_seconds: 60
environment: {}
kopia:
create_threads: 0
restore_threads: 8
retry_limit: 3
btrfs:
restore_threads: 4
create_read_only: true
zfs:
restore_threads: 4
pbs:
create_threads: 4
download_concurrency: 4
transfers:
download_limit: 0
docker:
socket: /var/run/docker.sock
server_name_in_container_name: false
delete_container_on_stop: true
network:
interface: '172.18.0.1'
disable_interface_binding: false
dns:
- '1.1.1.1'
- '1.0.0.1'
dns_options:
- ndots:0
- timeout:2
- attempts:3
- single-request-reopen
name: calagopus_nw
ispn: false
driver: bridge
mode: calagopus_nw
is_internal: false
enable_icc: true
network_mtu: 1500
interfaces:
v4:
enabled: true
subnet: 172.18.0.0/16
gateway: '172.18.0.1'
v6:
enabled: true
subnet: fdba:17c8:6c94::/64
gateway: fdba:17c8:6c94::1011
firewall:
backend: auto
source_file_max_entries: 10000
source_file_max_bytes: 1048576
bandwidth:
backend: auto
domainname: ''
registries: {}
registry_image_fetch_cache:
enabled: true
duration: 300
background_refresh: false
tmpfs_size: 100
shm_size: 0
container_pid_limit: 5120
container_apply_seccomp: true
container_apparmor_profile: ''
container_ulimits: []
container_sysctls: {}
numa_memory_binding: true
cpu_period: 100000
cfs_burst:
enabled: true
multiple: 1.0
startup_boost:
enabled: false
timeout: 120
max_concurrent: 3
runtime_boost:
enabled: false
threshold: 90
sustained: 10
multiple: 2.0
duration: 60
cooldown: 300
max_concurrent: 3
lxcfs:
enabled: false
directory: /var/lib/lxcfs
installer_limits:
timeout: 1800
memory: 1024
cpu: 100
overhead:
override: false
default_multiplier: 1.05
multipliers: {}
userns_mode: ''
mount_options: []
log_config:
type: local
config:
compress: 'false'
max-file: '1'
max-size: 5m
mode: non-blocking
limits:
server_concurrent_pulls: 3
server_concurrent_operations: 0
throttles:
enabled: true
lines: 2000
line_reset_interval: 100
tundra:
enabled: false
data_directory: '{root_directory}/tundra'
binary: ''
image: debian:trixie-slim
source_image: calagopus/tundra:latest
metrics_port: 7101
remote: https://panel.example.com
remote_headers: {}
remote_query:
timeout: 30
boot_servers_per_page: 50
retry_limit: 10
allowed_mounts: []
allowed_devices: []
allowed_origins: []
allow_cors_private_network: false
ignore_panel_config_updates: false
ignore_panel_wings_upgrades: false