Skip to main content
The StellarStack daemon is a Rust-based service that runs on each physical or virtual machine (node) in your infrastructure. It manages Docker containers, handles server lifecycle operations, and communicates with the central API.

​
Architecture Overview

The daemon implements a daemon-per-node architecture:
  • API Server (Hono + PostgreSQL) - Central control plane
  • Web Panel (Next.js 15) - Real-time dashboard
  • Daemon Nodes (Rust) - One per physical server, manages Docker containers
  • Database (PostgreSQL) - Single source of truth
Each daemon:
  • Manages Docker containers for game servers
  • Provides SFTP access for file management
  • Streams real-time console output via WebSocket
  • Reports resource usage to the API
  • Handles backups and archives

​
Prerequisites

Before installing the daemon:
  • Docker 20.10+ installed and running
  • Rust 1.70+ (for building from source)
  • Linux or macOS (Windows via WSL2)
  • Port 8080 available (configurable)
  • Port 2022 available for SFTP (configurable)

​
Installation

Download the pre-built binary for your platform: 
curl -L https://github.com/StellarStackOSS/StellarStack/releases/latest/download/stellar-daemon-linux-amd64 -o stellar-daemon
chmod +x stellar-daemon
sudo mv stellar-daemon /usr/local/bin/

​
Option 2: Build from Source

Clone and build the daemon: 
git clone https://github.com/StellarStackOSS/StellarStack.git
cd StellarStack/apps/daemon
cargo build --release
sudo cp target/release/stellar-daemon /usr/local/bin/

​
Configuration

The daemon uses a TOML configuration file. Create /etc/stellar-daemon/config.toml: 
# Enable debug logging
debug = false

[api]
host = "0.0.0.0"
port = 8080
upload_limit = 100  # MB
trusted_proxies = []

[api.ssl]
enabled = false
cert = ""
key = ""

[system]
root_directory = "/var/lib/stellar"
data_directory = "/var/lib/stellar/volumes"
backup_directory = "/var/lib/stellar/backups"
archive_directory = "/var/lib/stellar/archives"
tmp_directory = "/var/lib/stellar/tmp"
log_directory = "/var/lib/stellar/logs"
username = "stellar"
timezone = "UTC"
disk_check_interval = 60

[system.user]
uid = 1000
gid = 1000

[docker]
# Auto-detected based on OS. Uncomment to override:
# socket = "unix:///var/run/docker.sock"
tmpfs_size = 100  # MB
container_pid_limit = 512
dns = ["1.1.1.1", "1.0.0.1"]

[docker.network]
name = "bridge"
interface = "172.18.0.1"
driver = "bridge"
is_internal = false

[docker.installer_limits]
memory = 1024  # MB
cpu = 100      # 100% = 1 core

[docker.overhead]
default = 0

[remote]
url = "https://api.stellarstack.app"
token_id = "your-node-token-id"
token = "your-node-token"
timeout = 30
boot_servers_per_page = 50

[redis]
enabled = true
url = "redis://127.0.0.1:6379"
prefix = "stellar"

[sftp]
enabled = true
bind_address = "0.0.0.0"
bind_port = 2022
read_only = false
host_key = "/var/lib/stellar/ssh_host_key"

​
Configuration Reference

​
API Section

OptionTypeDefaultDescription
hoststring0.0.0.0Address to bind HTTP server
portinteger8080Port for API endpoints
upload_limitinteger100Max upload size in MB
trusted_proxiesarray[]IP addresses of trusted reverse proxies

​
System Section

OptionTypeDefaultDescription
root_directorystring.stellarRoot data directory
data_directorystring.stellar/volumesServer volume mounts
backup_directorystring.stellar/backupsBackup storage
archive_directorystring.stellar/archivesTransfer archives
tmp_directorystring.stellar/tmpTemporary files
log_directorystring.stellar/logsDaemon logs
usernamestringstellarUser for file ownership
timezonestringUTCTimezone for scheduling
disk_check_intervalinteger60Disk usage check interval (seconds)

​
Docker Section

OptionTypeDefaultDescription
socketstringAuto-detectedDocker socket path
tmpfs_sizeinteger100Tmpfs mount size in MB
container_pid_limitinteger512Max processes per container
dnsarray["1.1.1.1", "1.0.0.1"]DNS servers for containers

​
Remote Section

OptionTypeRequiredDescription
urlstringYesAPI server URL
token_idstringYesNode token ID from panel
tokenstringYesNode authentication token
timeoutintegerNoRequest timeout in seconds

​
Running the Daemon

​
Manual Start

Run the daemon with your config file: 
stellar-daemon --config /etc/stellar-daemon/config.toml
Enable debug logging: 
stellar-daemon --config /etc/stellar-daemon/config.toml --debug

​
Systemd Service

Create /etc/systemd/system/stellar-daemon.service: 
[Unit]
Description=StellarStack Daemon
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/stellar-daemon --config /etc/stellar-daemon/config.toml
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
Enable and start: 
sudo systemctl daemon-reload
sudo systemctl enable stellar-daemon
sudo systemctl start stellar-daemon
sudo systemctl status stellar-daemon

​
Node Registration

Before the daemon can communicate with the panel:
  1. Navigate to Admin → Nodes in the panel
  2. Click Create Node
  3. Fill in node details:
    • Name: Descriptive name (e.g., “US-East-1”)
    • FQDN: Daemon’s public hostname
    • Port: Daemon API port (default 8080)
    • Protocol: HTTP or HTTPS
    • Location: Logical grouping
  4. Copy the generated Token ID and Token
  5. Add them to your daemon’s config.toml under [remote]
  6. Restart the daemon

​
Diagnostics

Run the built-in diagnostics: 
stellar-daemon diagnostics
This checks:
  • Docker connectivity
  • Network configuration
  • File permissions
  • API connectivity
  • Configuration validity

​
Troubleshooting

​
Daemon won’t start

Check Docker socket permissions: 
sudo usermod -aG docker $USER
# Log out and back in
Verify Docker is running: 
docker ps

​
Cannot connect to API

Test connectivity: 
curl https://api.stellarstack.app/health
Check firewall rules: 
sudo ufw status
sudo ufw allow 8080/tcp

​
Containers not starting

Check Docker logs: 
docker logs <container-name>
Verify resource limits: Ensure your node has sufficient memory and CPU.

​
Security Considerations

The daemon runs with elevated privileges to manage Docker. Always:
  • Use firewall rules to restrict API access
  • Enable SSL/TLS in production
  • Keep the daemon binary updated
  • Use strong authentication tokens

​
Dropped Capabilities

For security hardening, the daemon drops these Linux capabilities from containers:
  • SETPCAP, MKNOD, AUDIT_WRITE
  • NET_RAW, DAC_OVERRIDE, FOWNER
  • SYS_ADMIN, SYS_MODULE, SYS_BOOT
  • And 20+ more (see source code)
This follows the principle of least privilege.

​
Next Steps

Docker Configuration

Deep dive into container settings

Custom Domains

Set up custom domains for servers

Build docs developers (and LLMs) love

Get started for freeTalk to us