We removed our free Sandbox April 25th.
You can read more on our blog.

Environment File


CLI Command examples on this page are always provided without the --application (shorthand -A) argument, assuming you’re running these commands in a connected folder (at creation or using the dotcloud connect command). For more details on connected folders, see Migrating to the CLI 0.9.

What is the Environment File?

When your application is built by the dotCloud platform, a file named environment.json is created in the home directory of each of your services.

This file contains a JSON-formatted dictionary with most of the configuration information of the services in your stack. You can use it to retrieve automatically the host, port, and password, of your databases, caches, and so on.

Here is an example of an environment file:

   "DOTCLOUD_DB_MYSQL_URL": "mysql://root:pass@7a96f954.dotcloud.com:7780",
   "DOTCLOUD_DB_MYSQL_PASSWORD": "B61J14)]U4^L}.najnyE",
   "DOTCLOUD_PROJECT": "demodcapp",
   "DOTCLOUD_DB_MYSQL_HOST": "7a96f954.dotcloud.com",

The environment file will contain the access information of database services in the same application. In the example, the MySQL database service named “db” is present.


The environment variables defined in environment.json are not related to the “Unix” environment. In the future, dotCloud will mirror them in the “Unix” environment.

Reading the Environment

To read an environment variable you need to load the environment file first. Since it is a JSON file, this is very easy from any language:



     // Read the file and convert the underlying JSON dictionary into a PHP array
     $env = json_decode(file_get_contents("/home/dotcloud/environment.json"), true);

     echo "Application Name: {$env['DOTCLOUD_PROJECT']}\n";



Add the “json” requirement to your Gemfile:

source :rubygems
gem 'json'

Then use the following snippet to parse environment.json:

env = JSON.parse(File.read('/home/dotcloud/environment.json'))

puts "Application Name: #{env['DOTCLOUD_SERVICE_NAME']}"


Add the “JSON” requirement in your Makefile.PL, e.g:

use ExtUtils::MakeMaker;

        NAME => "dummy",
        PREREQ_PM => {
           'JSON' => 0,


Adding “JSON” in the “requirements” list in your dotcloud.yml works too (but that’s dotCloud specific).

Then use the following snippet to parse environment.json:

use JSON;

open my $fh, "<", "/home/dotcloud/environment.json" or die $!;
my $data = JSON::decode_json(join '', <$fh>);

print  "Application name: $data->{DOTCLOUD_SERVICE_NAME}\n";


import json

with open('/home/dotcloud/environment.json') as f:
  env = json.load(f)

print 'Application Name: {0}'.format(env['DOTCLOUD_SERVICE_NAME'])


var fs = require('fs');

var env = JSON.parse(fs.readFileSync('/home/dotcloud/environment.json', 'utf-8'));

console.log('Application Name: ' + env['DOTCLOUD_SERVICE_NAME']);

Adding Environment Variables

You can set your own environment variables either from dotcloud.yml or directly from the command line with the dotcloud env command.

The first approach is quite simple, just list your variables in the environment dictionary of the concerned service in dotcloud.yml:

  type: python
    MODE: production
    API: http://www.externalapi.com/v1/

This approach is good for environment variables that never change across deployments of your application and that can be stored in your code repository. But —most of the time— the environment holds variables that always change across deployments of your application and that can’t be stored in your repository. A perfect example is third parties service credentials. Also, you must push your application again to change environment variables defined in dotcloud.yml.

The dotcloud env command solves these issues by allowing you to set environment variable from the command line, once the application is running on dotCloud:

dotcloud env set MYVAR=MYVALUE

Whereas dotcloud.yml allows you to define different environment variables for each service, dotcloud env set environment variables for the whole application. Moreover, environment variables set with dotcloud env supersede environment variables defined in dotcloud.yml.

You can set multiple variables at once:

dotcloud env set \
    'AWS_ACCESS_KEY=IA4F0njNcmKKg3YndpOe' \

You can list the variables you set with the list subcommand:

dotcloud env list


Your environment variables keys must be alphanumeric characters only and cannot start with “DOTCLOUD_”.

Removing Environment Variables

You can remove environment variables set in dotcloud.yml by editing the file and pushing your code again.

You can remove environment variables set “at runtime” with dotcloud env with the unset subcommand:

dotcloud env unset AWS_ACCESS_KEY

YAML Format

This document shows how to use environment.json but the environment is also available in the YAML format in the file environment.yaml.

If you think that another environment format is relevant, let us know at support@dotcloud.com.