Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Convention Driven Instance Autonomy


Forge is designed to facilitate autonomous server configuration. At first boot, a server should execute the bootstrap code, which will in turn:

  • Install the tools required for the rest of the code, using pip.
  • Determine the purpose of the server, using a handful of APIs.
  • Download any playbooks that are applicable to the server.
  • Install any Ansible roles those playbooks depend on.
  • Apply any playbooks downloaded in this way.

Forge is only actively tested against Amazon Web Services (AWS).


Forge will fulfill its own dependencies, if pip is available. If it is not, the following python packages must be available.


Forge testing uses the current Long-Term Support release of Ubuntu. However, it should run on any Linux with Python.

Forge 1.x is not compatible with Python3. This is resolvable with a minor change which breaks Python 2.x compatibility.


  • An S3 bucket to store roles in.
  • An IAM Role to apply to autonomous servers, with a User Policy granting access to the above bucket.
  • (optional) One or more Ansible Roles in the bucket.

Self-Discovery via Conventions

Forge will attempt to figure out what needs to happen on its own. To do this, Forge relies on conventions enforced by the tools it is typically used with.

These tools are optional, and Forge should be fine as long as you follow similar conventions.

Supported Resource Tags

Forge understands specific resource tags, and expects an instance to have them.

Resource Tag Description
Project The project this instance belongs to.
Role The purpose of this specific instance, within that project.
ForgeBucket The name of the S3 bucket Forge should pull from.
ForgeRegion The region to find ForgeBucket in.

If sufficient resource tags are not present, Forge will make reasonable guesses. It assumes security group naming like your-project-name-role, and infers implicit tags from this. Environment variables can provide additional data.


An untagged instance with two security groups named your-project-name-application and your-project-name-managed.

  • Project will be your-project-name.
  • ForgeBucket will read FORGE_BUCKET from the environment.
  • Role will be ['application', 'managed'], and Forge will configure both.
  • ForgeRegion will read FORGE_REGION from the environment.

Resource tags are explicit statements of intent, and discovery stops there. Everything else is a fallback.

How to Use (Hardcore Mode)

If running arbitrary code from the internet with root privileges and no human oversight excites you, this should do it.

curl | python

How to Use (Recommended)

For a more reasonable approach, upload to somewhere you control.

curl https://YOUR_URL_HERE/ | python





Convention-Driven Instance Autonomy for EC2







No packages published