https://github.com/tschaefer/finchctl
The Minimal Observability Infrastructure.
https://github.com/tschaefer/finchctl
alloy cmdline golang grafana logging loki
Last synced: about 1 month ago
JSON representation
The Minimal Observability Infrastructure.
- Host: GitHub
- URL: https://github.com/tschaefer/finchctl
- Owner: tschaefer
- License: mit
- Created: 2025-07-17T18:34:21.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-03-05T18:50:16.000Z (3 months ago)
- Last Synced: 2026-03-05T21:51:43.660Z (3 months ago)
- Topics: alloy, cmdline, golang, grafana, logging, loki
- Language: Go
- Homepage: https://blog.tschaefer.org/finch
- Size: 335 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# The Minimal Observability Infrastructure
[](https://github.com/tschaefer/finchctl/releases)
[](https://goreportcard.com/report/github.com/tschaefer/finchctl)
[](https://github.com/tschaefer/finchctl/graphs/contributors)
[](./LICENSE)
Finch brings production-grade observability to your infrastructure — no
Kubernetes, no cloud vendor, no expertise required. Deploy a full logs,
metrics, and profiling stack in one command. Enroll agents on any Linux or
macOS machine in one more. Everything else — TLS, authentication, agent
configuration — is handled for you.
> Background, motivation, and a walkthrough: [Blog post](https://blog.tschaefer.org/posts/2025/08/17/finch-a-minimal-logging-stack/)
## Getting Started
Install the Finch CLI:
```bash
curl -sSfL https://finch.coresec.zone | sudo sh -
```
Alternatively, download a binary from the
[releases page](https://github.com/tschaefer/finchctl/releases) or build from
source.
## Deploy the Stack
You need a Linux machine with SSH access and superuser privileges.
```bash
finchctl service deploy root@10.19.80.100
```
That's it. The full observability stack is up at `https://10.19.80.100`.
Open `/grafana` in your browser — user `admin`, password `admin`.
Your local mTLS credentials are saved automatically to `~/.config/finch.json`.
> Need Let's Encrypt or a custom certificate? See
[TLS options](https://tschaefer.github.io/finch-docs/deployment/tls-options/).
## Enroll an Agent
Register a new agent with the Finch service and deploy it to a target machine:
```bash
finchctl agent register \
--agent.hostname sparrow \
--agent.logs.journal \
10.19.80.100
```
The agent config is saved as `finch-agent.cfg` and contains all endpoints and
credentials.
```bash
finchctl agent deploy --agent.config finch-agent.cfg root@172.17.0.4
```
Alloy is installed and started on the target machine automatically.
> Want to collect Docker logs, log files, metrics, or profiles? See
[Agent options](https://tschaefer.github.io/finch-docs/agent/options/).
## Open the Dashboard
```bash
finchctl service dashboard --web --permission.session-timeout 1800 10.19.80.100
```
The dashboard opens in your browser with a fresh session token.
## What's Next
- [TLS options](https://tschaefer.github.io/finch-docs/deployment/tls-options/) - Let's Encrypt, custom certificates
- [Agent options](https://tschaefer.github.io/finch-docs/agent/options/) - Docker logs, file logs, metrics, profiles, labels
- [Managing agents](https://tschaefer.github.io/finch-docs/agent/manage/) - list, describe, edit, deregister
- [Token renewal](https://tschaefer.github.io/finch-docs/agent/token-renewal/) - refreshing agent credentials before expiry
- [Security model](https://tschaefer.github.io/finch-docs/security/) - how Finch handles auth, rotation, and recovery
- [Windows agents](https://tschaefer.github.io/finch-docs/agent/windows/) - enrolling agents on Windows
## Contributing
Fork the repository and submit a pull request. For major changes, open an issue
first to discuss your proposal.
## License
This project is licensed under the [MIT License](LICENSE).