Skip to content
A centralized paradigm of configuration management.
C# Ruby Python PowerShell Batchfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status

Often, multiple related projects will need access to the same configuration values, which can be problematic if the projects use different technologies. Typically, configuration values are then stored in multiple places, making managing these values difficult.

Centroid lets you take control of your configurations by making it easy to work with a central configuration file that is accessible by various languages using a single API. Currently, Centroid supports Python, .NET, and Ruby.

Key Features of Centroid

  • Unified API supports multiple languages
  • Convenient method for retrieving all configuration values for a specific environment: environment-specific values are merged with values that apply to all environments
  • Ability to use native-language conventions to look up a key (underscores and case are ignored)
  • Ability to load the configuration file as a file or a string

Using Centroid

To use Centroid, you must first install the package for each desired language. Refer to the language-specific documents for installation instructions.

Once a Centroid package is installed, complete the following two items. Examples of both items are available later in this document.

  1. Declare your application's configuration values in JSON.
  2. Create an instance of the Config class to use the API. Refer to the language-specific documents for details specific to each language.

Using Native-language Conventions

Because Centroid ignores underscores and case, you can use native-language conventions to look up a key.

For example, your JSON configuration file could use camelCase while your Config class uses snake_case, PascalCase, or camelCase as appropriate for the language.


JSON Configuration File

The following example demonstrates storing a database's server address configuration value.

    "database": {
        "serverAddress": "my-server.local"

However, applications typically have different configuration values for each environment. For example, dev and prod environments use different servers and user accounts. But applications usually also have configuration values that are the same across all environments.

To create an environment-based configuration, make the top-level objects in the JSON represent the various environments, as in the example below. List the configuration values specific to an environment under the appropriate top-level object.

Also create an all top-level object. List the configuration values that are the same across all environments within this all environment.

    "dev": {
        "someResource": {
            "server": "resource-dev.local"
    "prod": {
        "someResource": {
            "server": "resource-prod.local"
    "all": {
        "keys": {
            "ssh": "path/to/"

Note: Refer to the language-specific documents for information on using the environment instance method to retrieve environment-based configurations.

API (Config Class)

Note: These Config class examples assume a JSON configuration file with the following:

    "database": {
        "serverAddress": "my-server.local"

The following Python example demonstrates loading a file (config.json) and retrieving the database’s server address using a snake_case property (database.server_address).

config = Config.from_file("config.json")
server = config.database.server_address # => "my-server.local"

The following C# example demonstrates loading the JSON as a string and then retrieving the database's server address using a PascalCase property (Database.ServerAddress).

// MyApp.cs
var json = @"{ ""database"": { ""serverAddress"": ""my-server.local"" } }";
dynamic config = new Config(json);
var server = config.Database.ServerAddress; // => "my-server.local"

Refer to the language-specific documents for additional details about using the API, including examples of using the environment instance method.

Language-specific Documents

Each language has a separate document with information specific to that language.


See Contributing.


Thanks to all contributors!


Centroid is licensed under the MIT License.

You can’t perform that action at this time.