oci-arm-hunter

CI Latest Release License: MIT Shell: 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

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

The machine running the hunter must have oci-cli configured (oci setup config) with API key credentials.

Quick Start

# 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 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.

# 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:

# ntfy.sh (no account required)
NOTIFY_URL="https://ntfy.sh/your-unique-topic"

Install the ntfy app on your phone and subscribe to your topic.

Contributing

See CONTRIBUTING.md for the branch strategy, commit format, and PR process.

All commits must follow Conventional Commits. Scope is required — see CLAUDE.md for the project scope table.

License

MIT — David Sandoval, 2026