https://github.com/sandovaldavid/oci-arm-hunter
Automated hunter that retries the OCI API until an ARM Always Free instance becomes available and claims it immediately
https://github.com/sandovaldavid/oci-arm-hunter
always-free arm automation bash cloud-computing oci oracle-cloud
Last synced: 6 days ago
JSON representation
Automated hunter that retries the OCI API until an ARM Always Free instance becomes available and claims it immediately
- Host: GitHub
- URL: https://github.com/sandovaldavid/oci-arm-hunter
- Owner: sandovaldavid
- License: mit
- Created: 2026-06-20T18:19:41.000Z (11 days ago)
- Default Branch: main
- Last Pushed: 2026-06-20T19:13:28.000Z (11 days ago)
- Last Synced: 2026-06-20T20:11:41.662Z (11 days ago)
- Topics: always-free, arm, automation, bash, cloud-computing, oci, oracle-cloud
- Language: Shell
- Homepage: https://sandovaldavid.github.io/oci-arm-hunter
- Size: 34.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# oci-arm-hunter
[](https://github.com/sandovaldavid/oci-arm-hunter/actions/workflows/ci.yml)
[](https://github.com/sandovaldavid/oci-arm-hunter/releases/latest)
[](LICENSE)
[](https://www.gnu.org/software/bash/)
Automated hunter that retries the OCI API until an **ARM Always Free** instance (`VM.Standard.A1.Flex` — 4 OCPUs / 24 GB RAM) becomes available, then claims it immediately and notifies you.
> **Why this exists:** Oracle's Always Free ARM tier is perpetually out of capacity. The only reliable strategy is a persistent retry loop with rotating Availability Domains, jitter cooldown, and a running process that doesn't depend on your laptop staying on.
---
## Features
- Interactive setup wizard — fetches all OCI resource IDs automatically via `oci-cli` (no manual console hunting)
- Rotates across all Availability Domains on each retry
- Randomized cooldown jitter to avoid synchronized rate limiting
- Structured logging with timestamps to `cazador.log`
- Push notification on success (ntfy.sh / webhook)
- Single `Makefile` entry point for all operations
- `systemd` service support for true 24/7 unattended execution on an existing VM Micro
---
## Prerequisites
| Tool | Install |
|------|---------|
| `oci-cli` | `dnf install python3-oci-cli` or `pip install oci-cli` |
| `jq` | `apt install jq` / `dnf install jq` |
| `tmux` | `apt install tmux` / `dnf install tmux` (for `make run-bg`) |
| OCI account | [oracle.com/cloud/free](https://www.oracle.com/cloud/free/) |
The machine running the hunter must have `oci-cli` configured (`oci setup config`) with API key credentials.
---
## Quick Start
```bash
# 1. Clone and enter
git clone https://github.com/sandovaldavid/oci-arm-hunter.git
cd oci-arm-hunter
# 2. Run the interactive setup wizard (fetches OCIDs automatically)
make setup
# 3. Launch the hunter
make run # foreground — watch live output
make run-bg # background tmux session
make install # systemd service (recommended on a VM Micro)
```
---
## Makefile Reference
```
make help Show all available commands
make setup Interactive wizard to generate .env with your OCI config
make run Launch the hunter in the foreground (Ctrl+C to stop)
make run-bg Launch in a persistent tmux session (background)
make logs Follow the log in real time
make status Check if the hunter is running (tmux or systemd)
make stop Kill the tmux session
make install Install as a systemd service (survives reboots)
make uninstall Remove the systemd service
```
---
## Configuration
All configuration lives in `.env` (generated by `make setup`). See [`.env.example`](.env.example) for all available variables.
| Variable | Description |
|----------|-------------|
| `TENANCY_OCID` | Auto-fetched from `~/.oci/config` |
| `COMPARTMENT_OCID` | Selected interactively |
| `SUBNET_OCID` | Selected interactively (public subnet) |
| `AVAILABILITY_DOMAINS` | Auto-fetched; all ADs are rotated during retries |
| `IMAGE_OCID` | Selected interactively from available ARM images |
| `SHAPE` | `VM.Standard.A1.Flex` (fixed) |
| `OCPUS` / `MEMORY_GB` | `4` / `24` (Always Free maximum) |
| `SSH_PUBLIC_KEY` | Paste your Ed25519 public key (from Bitwarden or similar) |
| `COOLDOWN_MIN/MAX` | Retry wait range in seconds (default: 45–75) |
| `NOTIFY_URL` | Optional webhook — ntfy.sh, Telegram, Discord |
---
## Architecture
```
[ Your machine / VM.Standard.E2.1.Micro ]
|
+---> Reads .env configuration
|
+---> oci-cli (authenticated via ~/.oci/config)
|
+---> [ Retry loop ]
|
+---------+---------+
v No capacity v PROVISIONING
Wait + jitter Log success
Rotate AD Send notification
Retry Exit
```
---
## 24/7 Unattended Execution
The recommended host is an existing **VM.Standard.E2.1.Micro** (also Always Free). Running inside Oracle's network gives near-zero latency to the OCI API.
```bash
# Option A: tmux (quick start)
make run-bg # detaches automatically
make logs # reconnect to follow progress
# Option B: systemd (recommended — survives VM reboots)
make install
sudo journalctl -fu cazador-arm
```
---
## Notifications
Set `NOTIFY_URL` in `.env` to receive a push notification when the VM is claimed:
```bash
# ntfy.sh (no account required)
NOTIFY_URL="https://ntfy.sh/your-unique-topic"
```
Install the [ntfy app](https://ntfy.sh/) on your phone and subscribe to your topic.
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for the branch strategy, commit format, and PR process.
All commits must follow [Conventional Commits](https://www.conventionalcommits.org/). Scope is required — see [CLAUDE.md](CLAUDE.md) for the project scope table.
---
## License
[MIT](LICENSE) — David Sandoval, 2026