{"id":51143833,"url":"https://github.com/sandovaldavid/oci-arm-hunter","last_synced_at":"2026-06-26T01:02:28.369Z","repository":{"id":366211497,"uuid":"1275468326","full_name":"sandovaldavid/oci-arm-hunter","owner":"sandovaldavid","description":"Automated hunter that retries the OCI API until an ARM Always Free instance becomes available and claims it immediately","archived":false,"fork":false,"pushed_at":"2026-06-20T19:13:28.000Z","size":35,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T20:11:41.662Z","etag":null,"topics":["always-free","arm","automation","bash","cloud-computing","oci","oracle-cloud"],"latest_commit_sha":null,"homepage":"https://sandovaldavid.github.io/oci-arm-hunter","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sandovaldavid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T18:19:41.000Z","updated_at":"2026-06-20T18:22:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sandovaldavid/oci-arm-hunter","commit_stats":null,"previous_names":["sandovaldavid/oci-arm-hunter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sandovaldavid/oci-arm-hunter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandovaldavid%2Foci-arm-hunter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandovaldavid%2Foci-arm-hunter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandovaldavid%2Foci-arm-hunter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandovaldavid%2Foci-arm-hunter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sandovaldavid","download_url":"https://codeload.github.com/sandovaldavid/oci-arm-hunter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandovaldavid%2Foci-arm-hunter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34798183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["always-free","arm","automation","bash","cloud-computing","oci","oracle-cloud"],"created_at":"2026-06-26T01:02:24.726Z","updated_at":"2026-06-26T01:02:28.234Z","avatar_url":"https://github.com/sandovaldavid.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# oci-arm-hunter\n\n[![CI](https://github.com/sandovaldavid/oci-arm-hunter/actions/workflows/ci.yml/badge.svg)](https://github.com/sandovaldavid/oci-arm-hunter/actions/workflows/ci.yml)\n[![Latest Release](https://img.shields.io/github/v/release/sandovaldavid/oci-arm-hunter)](https://github.com/sandovaldavid/oci-arm-hunter/releases/latest)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Shell: Bash](https://img.shields.io/badge/Shell-Bash-4EAA25?logo=gnu-bash\u0026logoColor=white)](https://www.gnu.org/software/bash/)\n\nAutomated 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.\n\n\u003e **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.\n\n---\n\n## Features\n\n- Interactive setup wizard — fetches all OCI resource IDs automatically via `oci-cli` (no manual console hunting)\n- Rotates across all Availability Domains on each retry\n- Randomized cooldown jitter to avoid synchronized rate limiting\n- Structured logging with timestamps to `cazador.log`\n- Push notification on success (ntfy.sh / webhook)\n- Single `Makefile` entry point for all operations\n- `systemd` service support for true 24/7 unattended execution on an existing VM Micro\n\n---\n\n## Prerequisites\n\n| Tool | Install |\n|------|---------|\n| `oci-cli` | `dnf install python3-oci-cli` or `pip install oci-cli` |\n| `jq` | `apt install jq` / `dnf install jq` |\n| `tmux` | `apt install tmux` / `dnf install tmux` (for `make run-bg`) |\n| OCI account | [oracle.com/cloud/free](https://www.oracle.com/cloud/free/) |\n\nThe machine running the hunter must have `oci-cli` configured (`oci setup config`) with API key credentials.\n\n---\n\n## Quick Start\n\n```bash\n# 1. Clone and enter\ngit clone https://github.com/sandovaldavid/oci-arm-hunter.git\ncd oci-arm-hunter\n\n# 2. Run the interactive setup wizard (fetches OCIDs automatically)\nmake setup\n\n# 3. Launch the hunter\nmake run          # foreground — watch live output\nmake run-bg       # background tmux session\nmake install      # systemd service (recommended on a VM Micro)\n```\n\n---\n\n## Makefile Reference\n\n```\nmake help         Show all available commands\nmake setup        Interactive wizard to generate .env with your OCI config\nmake run          Launch the hunter in the foreground (Ctrl+C to stop)\nmake run-bg       Launch in a persistent tmux session (background)\nmake logs         Follow the log in real time\nmake status       Check if the hunter is running (tmux or systemd)\nmake stop         Kill the tmux session\nmake install      Install as a systemd service (survives reboots)\nmake uninstall    Remove the systemd service\n```\n\n---\n\n## Configuration\n\nAll configuration lives in `.env` (generated by `make setup`). See [`.env.example`](.env.example) for all available variables.\n\n| Variable | Description |\n|----------|-------------|\n| `TENANCY_OCID` | Auto-fetched from `~/.oci/config` |\n| `COMPARTMENT_OCID` | Selected interactively |\n| `SUBNET_OCID` | Selected interactively (public subnet) |\n| `AVAILABILITY_DOMAINS` | Auto-fetched; all ADs are rotated during retries |\n| `IMAGE_OCID` | Selected interactively from available ARM images |\n| `SHAPE` | `VM.Standard.A1.Flex` (fixed) |\n| `OCPUS` / `MEMORY_GB` | `4` / `24` (Always Free maximum) |\n| `SSH_PUBLIC_KEY` | Paste your Ed25519 public key (from Bitwarden or similar) |\n| `COOLDOWN_MIN/MAX` | Retry wait range in seconds (default: 45–75) |\n| `NOTIFY_URL` | Optional webhook — ntfy.sh, Telegram, Discord |\n\n---\n\n## Architecture\n\n```\n[ Your machine / VM.Standard.E2.1.Micro ]\n         |\n         +---\u003e Reads .env configuration\n         |\n         +---\u003e oci-cli (authenticated via ~/.oci/config)\n         |\n         +---\u003e [ Retry loop ]\n                    |\n          +---------+---------+\n          v No capacity       v PROVISIONING\n   Wait + jitter          Log success\n   Rotate AD              Send notification\n   Retry                  Exit\n```\n\n---\n\n## 24/7 Unattended Execution\n\nThe 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.\n\n```bash\n# Option A: tmux (quick start)\nmake run-bg        # detaches automatically\nmake logs          # reconnect to follow progress\n\n# Option B: systemd (recommended — survives VM reboots)\nmake install\nsudo journalctl -fu cazador-arm\n```\n\n---\n\n## Notifications\n\nSet `NOTIFY_URL` in `.env` to receive a push notification when the VM is claimed:\n\n```bash\n# ntfy.sh (no account required)\nNOTIFY_URL=\"https://ntfy.sh/your-unique-topic\"\n```\n\nInstall the [ntfy app](https://ntfy.sh/) on your phone and subscribe to your topic.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the branch strategy, commit format, and PR process.\n\nAll commits must follow [Conventional Commits](https://www.conventionalcommits.org/). Scope is required — see [CLAUDE.md](CLAUDE.md) for the project scope table.\n\n---\n\n## License\n\n[MIT](LICENSE) — David Sandoval, 2026\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandovaldavid%2Foci-arm-hunter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsandovaldavid%2Foci-arm-hunter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandovaldavid%2Foci-arm-hunter/lists"}