https://github.com/dturovskiy/armactl
Installer, manager and TUI for Arma Reforger Dedicated Server on Ubuntu
https://github.com/dturovskiy/armactl
ar arma arma-reforger dedicated-server gameserver linux python steamcmd systemd textual tui ubuntu
Last synced: 23 days ago
JSON representation
Installer, manager and TUI for Arma Reforger Dedicated Server on Ubuntu
- Host: GitHub
- URL: https://github.com/dturovskiy/armactl
- Owner: dturovskiy
- License: mit
- Created: 2026-03-27T04:47:16.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-13T17:12:05.000Z (about 1 month ago)
- Last Synced: 2026-05-13T17:19:36.555Z (about 1 month ago)
- Topics: ar, arma, arma-reforger, dedicated-server, gameserver, linux, python, steamcmd, systemd, textual, tui, ubuntu
- Language: Python
- Homepage: https://github.com/dturovskiy/armactl/releases/latest
- Size: 1.73 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
- Roadmap: docs/roadmap.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# armactl
[](https://github.com/dturovskiy/armactl/actions/workflows/ci.yml)
[](https://github.com/dturovskiy/armactl/releases)
[](LICENSE)
[](pyproject.toml)
[](README.md)
Installer, manager, and TUI for **Arma Reforger Dedicated Server** on Ubuntu.
`armactl` is built for operators who want one tool that can install a server
from scratch, detect an existing installation, repair broken state, manage
`systemd`, edit `config.json`, work with mods, and optionally expose a Telegram
admin bot.
## Screenshot
## Who this is for
- Ubuntu 24.04 hosts
- single dedicated server instance
- single Linux user
- operators who prefer a repo-local launcher over global package setup
## Quick start
```bash
git clone https://github.com/dturovskiy/armactl.git
cd armactl
./armactl
```
On first run, `./armactl` bootstraps the repo-local environment automatically
and then opens the TUI. After that, keep using the same launcher: no PATH
changes, no manual venv activation.
If you want the development toolchain from the first launch too, use:
```bash
ARMACTL_BOOTSTRAP_MODE=--dev ./armactl
```
## Core scenarios
### Fresh host
Use `./armactl` on a clean Ubuntu host and choose `Install New Server`.
`armactl` will bootstrap the environment, install SteamCMD if needed, download
the server, create config and runtime directories, generate `systemd` units,
and start the service.
### Existing server
Use `Detect Existing Server` or `Manage Existing Server`. `armactl` will look
for the runtime root, `config.json`, `systemd` service, timer, and current
ports, then switch into management mode without reinstalling the server.
### Broken install / repair
Use `Repair Installation` in the TUI or:
```bash
armactl repair
```
Repair re-checks the installation, validates or regenerates missing pieces,
rebuilds service and timer files, reinstalls the secure helper when needed, and
refreshes `state.json`.
## What armactl does
- install a server from scratch via SteamCMD
- detect and manage an existing installation
- start, stop, restart, and inspect the server
- safely edit `config.json`, with an optional raw JSON screen
- manage mods: add, remove, dedupe, import, export
- manage scheduled restarts through `systemd`
- expose optional Telegram bot controls
- show real Arma Reforger server FPS/frame-time telemetry when `-logStats` data is available
- keep runtime data separated from repo code
## Scheduled restarts
In TUI, `Restart Schedule` accepts exact times instead of raw `systemd` syntax:
```text
08:00
08:00, 20:00
08:00 20:00
```
`armactl` converts those values into the correct `OnCalendar=` entries in the
timer unit automatically.
## Server FPS telemetry
`armactl` can show real Arma Reforger Dedicated Server FPS and frame-time
telemetry.
For generated services, `start-armareforger.sh` starts the server with:
```text
-logStats 10000
```
The server writes periodic engine telemetry into the runtime console log, and
`armactl` reads the latest valid `FPS:` line from:
```text
~/armactl-data//config/logs/*/console.log
```
Example:
```text
Server FPS: 60.0
Frame time: 16.7 ms avg / 18.5 ms max
Telemetry: 4s old
```
This value is the server engine's own FPS telemetry. It is not estimated from
CPU usage.
For existing installations, regenerate the service/start script and restart the
server after updating `armactl` so the process starts with `-logStats 10000`.
## Runtime layout
`armactl` separates three layers:
| Layer | Location | Purpose |
|-------|----------|---------|
| Source code | this repository | CLI + TUI + backend modules |
| Runtime data | `~/armactl-data/default/` | server files, config, backups, state |
| System services | `/etc/systemd/system/` | auto-start and scheduled restarts |
Typical runtime structure:
```text
~/armactl-data/default/
├── server/
├── config/config.json
├── backups/
├── state.json
└── start-armareforger.sh
```
## Telegram bot
Telegram bot management is optional and runs as a separate `systemd` unit:
- `armactl-bot.service`
- TUI settings screen: `Manage Existing Server -> Telegram Bot`
- instance-scoped `.env` as the single source of truth for bot settings
Runtime config path:
```text
~/armactl-data//bot/.env
```
The repository ships [.env.example](.env.example) as a template, while real
runtime `.env` files stay out of git.
Current bot capabilities include:
- status
- metrics
- details
- start / stop / restart
- scheduled restart management
- player visibility through A2S and local RCON
- real Server FPS/frame-time metrics when server telemetry is available
See [docs/telegram-bot.md](docs/telegram-bot.md) for the full flow.
## Documentation
- [Architecture](docs/architecture.md)
- [Localization](docs/localization.md)
- [Telegram Bot](docs/telegram-bot.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Development](docs/development.md)
- [Release Process](docs/release-process.md)
- [Roadmap](docs/roadmap.md)
- [Checklist](docs/checklist.md)
## CLI commands
```text
armactl detect
armactl install
armactl repair
armactl start
armactl stop
armactl restart
armactl status
armactl logs
armactl ports
armactl config show
armactl config validate
armactl mods list
armactl mods add
armactl mods remove
armactl mods dedupe
armactl mods export FILE
armactl mods import FILE
armactl schedule show
armactl schedule set
armactl schedule enable
armactl schedule disable
```
## Development
```bash
./scripts/run-host-tests
.venv/bin/pytest
.venv/bin/ruff check src tests
```
If the repo was only bootstrapped in prod mode before, both `./armactl` and
`./scripts/run-host-tests` will refresh the repo-local `.venv` automatically
after `pyproject.toml` dependency changes.
## Project health
- [Contributing](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Security Policy](SECURITY.md)
- [Support](SUPPORT.md)
- [Changelog](CHANGELOG.md)
## License
MIT