# oracle-freetier-instance-creation retries the OCI API until capacity frees up

> oracle-freetier-instance-creation is a Python and shell script set that keeps calling the Oracle Cloud Infrastructure API to create a Free Tier ARM or AMD instance, retrying every 60 seconds so you do not have to sit in the console watching for capacity. It suits Oracle Cloud users who keep hitting Out of host capacity, and it does not finish the job for you, since no public IP is configured until you do that yourself.

**mohankumarpaluru/oracle-freetier-instance-creation** — A script to create free instance

- Repository: https://github.com/mohankumarpaluru/oracle-freetier-instance-creation
- Stars: 555 · Forks: 131
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/mohankumarpaluru-oracle-freetier-instance-creation

## The problem is capacity, not configuration

The README states the motivation directly. This project provides Python and shell scripts to automate the creation of Oracle Free Tier ARM instances, with 2 OCPU and 12 GB RAM, or the Oracle Free Tier AMD instance with 1 OCPU and 1 GB RAM, with minimal manual intervention.

The reason to automate it is stated in the same paragraph. Acquiring resources in certain availability domains can be challenging due to high demand, and repeatedly attempting creation through the Oracle console is impractical. The README mentions that other methods like the OCI CLI and PHP are available and links them at the end, and this solution implements the same thing in Python to streamline the process.

The summary line is blunt about what the script is for: it is another way to bypass the Out of host capacity or Out of capacity for shape VM.Standard.A1.Flex error and create an instance when the resources are freed up.

That framing matters for expectations. This is a waiting tool, not a provisioning tool. It does not make capacity appear, and it does not make an instance cheaper. It removes the human from the retry loop.

## The retry loop, the marker file and the email notification

The mechanism is straightforward and the documentation describes it precisely.

The script attempts to create an instance every 60 seconds, or as specified by the REQUEST_WAIT_TIME_SECS variable in the oci.env file, until the instance is successfully created. When it succeeds, a file named INSTANCE_CREATED is generated in the project directory, containing details about the newly created instance. You can also configure the script to send a Gmail notification on creation.

Three details make this workable in practice. The wait interval is configurable rather than fixed, so a user in a region with slower capacity turnover can back off. The INSTANCE_CREATED marker file is a durable, greppable record of what happened and its parameters, which is what you check after the script has been running unattended for hours. And the email notification means you can leave the loop running and find out when it succeeded rather than polling the console.

The feature list adds the rest of the configuration surface: a single file needs to be run after basic setup, configurable wait time and DISPLAY_NAME, Gmail notification, SSH keys for ARM instances can be automatically created, OS configuration based on Image ID or OS and version, and compute shape configuration.

The one gap the README calls out is a public IP. The note says the script does not configure a public IP by default and that you need to configure it after the instance is created from the console, with automating it planned for later.

## Prerequisites: a sacrificial micro instance, an API key and a free tier domain

The Pre-Requisites section is where most of the friction lives, and one item in particular is unusual.

You need a VM.Standard.E2.1.Micro instance, and the script is designed for a Ubuntu environment, specifically Ubuntu 22.04. The README says to create an always-free instance of that shape, and that this instance can be deleted after the ARM instance creation, and that it is not required if an existing OCI_SUBNET_ID is defined in the oci.env file. So the bootstrap is a small always-free instance that exists to have a subnet the script can point at, and it can be thrown away afterwards.

You also need an OCI API key, generated from your profile page under API Keys, and the config details copied during that creation, along with an OCI Free Availability Domain, which you identify as the eligible always-free tier domain during instance creation.

The optional piece is a Gmail App Passkey. If you want the email notification and have two-factor authentication enabled, you create a custom app in Google and obtain the passkey, following the linked Google App Passwords generation instructions.

The requirements.txt is small: oci, paramiko, python-dotenv and requests. Paramiko is there for the SSH key generation, since the script can create SSH keys for the ARM instance automatically.

## Setup: three files and two shell scripts

The setup is five steps, and two of them can be done interactively.

You SSH into the micro instance, clone the repository and change the permissions of setup_init.sh to make it executable:

```bash
    git clone https://github.com/mohankumarpaluru/oracle-freetier-instance-creation.git
    cd oracle-freetier-instance-creation
```

Then you create a file named oci_api_private_key.pem containing your API private key, where the name and path can be anything as long as the current user has read access. You create a file named oci_config inside the repository directory with the config details copied during API key creation, referring to sample_oci_config, and in that file you fill in the key_file field with the absolute path of your oci_api_private_key.pem.

Next you edit the oci.env file with the necessary details. That can be done by hand, or the setup_env.sh script can generate it interactively:

```bash
    ./setup_env.sh
```

That script guides you through the process of configuring your instance settings, including the instance name, compute shape, optional Gmail notifications and more. If an oci.env file already exists, the script creates a backup of the current file as oci.env.bak, which is a small thing that saves a real mistake when you rerun it.

Finally, you run setup_init.sh from the project directory, and it installs the required dependencies and starts the Python program in the background:

```bash
./setup_init.sh
```

The script shows an error prompt if an issue arises, and otherwise prints Script is running successfully. API call details go to launch_instance.log, with the parameters used recorded alongside.

## What it does not do, and the alternative paths

Two limitations are stated rather than discovered.

The public IP is the first. The script stops once the instance exists, and attaching a public IP remains a manual console step, which means the script will happily report success for an instance you cannot yet reach over the internet.

The second is the environment it runs in. The script is designed for a Ubuntu VM.Standard.E2.1.Micro instance. If you run it on your local machine instead, the README says to make sure you fill in the OCI_SUBNET_ID. There is also a first-run prompt about daemons using outdated libraries on a fresh instance, which the README attributes to updating libraries through apt update, and which will not be asked again.

The alternative approaches named in the README are the OCI CLI and the PHP route, both linked at the end. The difference in approach is worth stating: the CLI is the vendor's own client, so it changes as Oracle's API and flags change, whereas this script pins a small set of dependencies and a single main.py, and reads its parameters from oci.env. The trade is between tracking upstream changes and owning a small script you can read in one sitting.

The licence is MIT, with a LICENSE file in the repository root, and the repository also carries a TROUBLESHOOTING.md, a sample_oci_config, an email_content.html for the notification, a .github directory and a .gitignore.

## Conclusion

Adopt this script if you are trying to provision an Oracle Free Tier instance and keep losing the race for capacity, since the retry loop is the whole point and it saves you from manually refreshing the console. Do not adopt it expecting a complete deployment, because the README states plainly that the script does not configure a public IP by default and that you must do it yourself from the console afterwards. Before you run it, read TROUBLESHOOTING.md, prepare the API key, the oci_config and the oci.env file, and note the maintenance picture, where v1.3 was published on 2024-05-12 and the last push was on 2026-08-23.

## FAQ

### How does oracle-freetier-instance-creation work?

The script attempts to create an instance every 60 seconds, or as set by the REQUEST_WAIT_TIME_SECS variable in the oci.env file, until it succeeds. On success it writes a file named INSTANCE_CREATED in the project directory with the details of the new instance, and it can optionally send a Gmail notification.

### What do I need before running the Oracle Free Tier instance creation script?

A VM.Standard.E2.1.Micro Ubuntu 22.04 instance to run from, unless an existing OCI_SUBNET_ID is set in oci.env, plus an OCI API key and config, and the free tier availability domain to target. A Gmail App Passkey is optional and only needed for the email notification.

### Does the script attach a public IP to the instance it creates?

No. The README states that the script does not configure a public IP by default and that you need to configure it after creation from the console, with automating it planned for later.

### How do I configure the instance settings for oracle-freetier-instance-creation?

You edit the oci.env file with the necessary details, or run the setup_env.sh script, which generates it interactively and guides you through the instance name, compute shape and optional Gmail notifications. If oci.env already exists, setup_env.sh backs it up as oci.env.bak.

### What does setup_init.sh do in the Oracle Free Tier instance creation project?

It installs the required dependencies and starts the Python program in the background. The script prints an error prompt if an issue arises and otherwise shows that it is running successfully, with the API call details written to launch_instance.log.

## Sources

- [Issues](https://github.com/mohankumarpaluru/oracle-freetier-instance-creation/issues)
- [License: MIT](https://github.com/mohankumarpaluru/oracle-freetier-instance-creation/blob/main/LICENSE)
- [mohankumarpaluru/oracle-freetier-instance-creation on GitHub](https://github.com/mohankumarpaluru/oracle-freetier-instance-creation)
- [README](https://github.com/mohankumarpaluru/oracle-freetier-instance-creation/blob/main/README.md)
- [Releases](https://github.com/mohankumarpaluru/oracle-freetier-instance-creation/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mohankumarpaluru-oracle-freetier-instance-creation