A runtime orchestrator for Factorio game instances, managing mods, runtimes, and server configurations.
factctl is a command-line tool designed to simplify the management of Factorio game instances. It provides a unified interface for creating, configuring, and running Factorio instances with different mod sets, versions, and configurations.
- Instance Management: Create, update, and remove Factorio instances
- Mod Management: Install and manage mods from multiple sources (Portal, GitHub, Git)
- Runtime Management: Handle different Factorio versions and runtime environments
- Log Streaming: Real-time log monitoring and historical log access
- Configuration Management: JSON/JSONC configuration files with validation
- Cross-Platform: Works on Windows, macOS, and Linux
- Go 1.24.5 or later
- Factorio installation (install via Steam, direct download, or package manager)
git clone https://github.com/WhyIsSandwich/factctl.git
cd factctl
go build -o factctl cmd/factctl/main.go# Install to your PATH
sudo cp factctl /usr/local/bin/
# Or install to a local directory
mkdir -p ~/bin
cp factctl ~/bin/
export PATH="$HOME/bin:$PATH"# Create a basic instance
factctl up my-server
# Create a headless server instance
factctl up my-server --headless
# Create an instance with a configuration file
factctl up my-server --config ./server-config.jsonc# Launch the instance
factctl run my-server
# Launch in headless mode
factctl run my-server --headless# Stream live logs
factctl logs my-server
# Show recent logs without following
factctl logs my-server --no-follow# Remove instance
factctl down my-server
# Remove with backup
factctl down my-server --backupInstance configurations are stored as JSON/JSONC files. Here's an example:
factctl supports multiple mod sources:
- Portal:
portal:modname- Download from Factorio mod portal - GitHub:
github:user/repo- Clone and build from GitHub repository - Git:
git:https://example.com/repo.git- Clone from any Git repository
~/.config/factctl/ # Base directory (Linux)
├── instances/ # Instance directories
│ └── my-server/
│ ├── config/
│ │ ├── instance.json
│ │ ├── mod-list.json
│ │ └── server-settings.json
│ ├── mods/ # Installed mods
│ ├── saves/ # Save files
│ └── factorio.log # Instance logs
├── runtimes/ # Factorio installations
└── backups/ # Instance backups
Create or update an instance.
Options:
--config <path>: Path to configuration file--headless: Run in headless mode--base-dir <path>: Override base directory
Examples:
factctl up my-server
factctl up my-server --config ./config.jsonc
factctl up my-server --headlessRemove an instance.
Options:
--backup: Create backup before removal
Examples:
factctl down my-server
factctl down my-server --backupLaunch a Factorio instance.
Options:
--headless: Override headless mode--base-dir <path>: Override base directory
Examples:
factctl run my-server
factctl run my-server --headlessStream or view instance logs.
Options:
--no-follow: Show recent logs without following
Examples:
factctl logs my-server
factctl logs my-server --no-followYou can manage multiple instances simultaneously:
# Create different instances
factctl up vanilla-server
factctl up modded-server --config ./modded-config.jsonc
factctl up creative-server --config ./creative-config.jsonc
# Run different instances
factctl run vanilla-server &
factctl run modded-server &For mod development, you can use Git sources:
{
"name": "dev-server",
"version": "1.1",
"mods": {
"enabled": ["base", "my-mod"],
"sources": {
"my-mod": "git:https://github.com/user/my-mod.git"
}
}
}For dedicated servers:
{
"name": "production-server",
"version": "1.1",
"headless": true,
"port": 34197,
"server": {
"name": "Production Server",
"max_players": 20,
"public": true,
"password": "secure-password",
"admins": ["admin1", "admin2"],
"auto_save": true,
"auto_save_interval": 5
}
}Instance not found:
# Check if instance exists
ls ~/.config/factctl/instances/
# Recreate instance
factctl up my-serverFactorio not found:
# Check if Factorio is installed
which factorio
# Install Factorio via your preferred method:
# - Steam: Purchase and install through Steam
# - Direct: Download from factorio.com
# - Package manager: Use your system's package managerPermission errors:
# Check directory permissions
ls -la ~/.config/factctl/
# Fix permissions if needed
chmod -R 755 ~/.config/factctl/Instance logs are stored in the instance directory:
factorio.log- Current log filefactorio.log.1,factorio.log.2, etc. - Rotated log files
Backups are created in the backups/ directory:
# List available backups
ls ~/.config/factctl/backups/
# Restore from backup (manual process)
tar -xzf ~/.config/factctl/backups/my-server-20240101-120000.tar.gz# Build for current platform
go build -o factctl cmd/factctl/main.go
# Build for specific platform
GOOS=linux GOARCH=amd64 go build -o factctl-linux cmd/factctl/main.go# Run tests
go test ./...
# Run tests with coverage
go test -cover ./...- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
Licensed under the Apache License 2.0. See LICENSE for details.
- Web interface for instance management
- Plugin system for custom mod sources
- Docker support for containerized instances
- Multi-user support with permissions
- Instance templates and presets
- Automated backup scheduling
- Performance monitoring and metrics
- Real mod download integration (Portal API)
- Advanced mod dependency resolution
{ "name": "my-server", "version": "1.1", "headless": true, "port": 34197, "save_file": "my-world.zip", "mods": { "enabled": ["base", "bobmods", "angelsmods"], "sources": { "bobmods": "portal:bobmods", "angelsmods": "github:Angel-666/AngelMods" } }, "server": { "name": "My Factorio Server", "max_players": 8, "public": false, "password": "secret123", "admins": ["admin1", "admin2"], "auto_save": true, "auto_save_interval": 10 } }