The goal of this section is to explain how to use ADE on a project that provides an ADE configuration. See Setup for more information.

ADE Home

ADE needs a directory on the host which will be mounted as the user’s home directory within the container. It will be populated with dotfiles and must be different than the user’s home directory on the host. In case you use ADE for multiple projects it is recommended to use dedicated ADE home directories for each project.

ADE will look for a directory containing a file named .adehome starting with the current working directory and continuing with the parent directories to identify the ADE home directory to be mounted.

mkdir adehome
cd adehome
touch .adehome

Quick start

To start ade, an .aderc file is needed. For an example, see the Autoware.Auto project. For instructions to create an .aderc file for a project, see Setup.

When ade is run for the first time, it will first prompt for an authentication token, and then download all the Docker images configured in the .aderc file

$ cd adehome/path/to/.aderc
$ ade start --update
ADE startup completed.
$ ade enter
ade$ <= Note that the prompt changes



ADE Development Environment.



--rc <rc>

Specify a different ADE configuration file. The file should be in adehome or its subdirectories. [default: .aderc]


Start environment from within ADE project.

See ade --help for global options (e.g. how to set a non-default aderc)

ADDARGS are directly passed to docker run. To pass options, separate them with -- from the preceding ade options.

See and Custom docker run arguments for more information.

ade start [OPTIONS] [ADDARGS]...


--update, --no-update

Pull docker registries for updates. Using –update will imply –force.

--enter, --no-enter

Enter environment after starting.

-f, --force, --no-force

Force restart of running environment.

--select <select>

Select image tags to be used instead of configured defaults. Valid image tags are git tags and branches. To select one for a specific image use IMAGE:TAG (e.g. ade:ftr123) and only TAG to select it for all images for which it exists (e.g. release-42).



Optional argument(s)


Enter environment, running optional command.

The environment is defined by the variable ADE_NAME, set either as an environment variable or through the --rc option. If ADE_NAME is not defined, use ade as default name.

If the specified environment is not running, select among the available environments from an interactive prompt.

ade enter [OPTIONS] [CMD]


-u, --user <user>

Enter ade as given user (e.g. root) instead of default



Optional argument

Environment variables


Provide a default for CMD


Stop ade environment.

ade stop [OPTIONS]


Save configuration and images of running ADE into DIRECTORY.




Required argument


Load images from DIRECTORY.




Required argument


Update ade command-line interface.

ade update-cli [OPTIONS]


--finish-update <finish_update>

Used internally by update mechanism

Environment Variables

It is also possible to configure the default behavior of ade using environment variables and the .aderc file. For more information, see Configuring ADE with environment variables and The .aderc File.


Over time, unused Docker images, containers, and volumes will clutter the machine’s hard drive. ADE does not store anything valuable inside the Docker containers, so it is possible to use native Docker commands to clean up. Anything valuable that needs to persist should be placed in ade-home, which is stored on the host and mounted in ADE.

To get an overview of Docker’s disk usage, run:

$ docker system df
TYPE                TOTAL               ACTIVE              SIZE                RECLAIMABLE
Images              13                  11                  14.03GB             916.9MB (6%)
Containers          11                  0                   2.311MB             2.311MB (100%)
Local Volumes       17                  15                  5.411GB             17.8MB (0%)
Build Cache         0                   0                   0B                  0B

Docker provides a cleanup command that will remove everything that is unused. To properly determine what is unused, make sure that all Docker containers you want to keep are running. To avoid having to re-download ADE images, run ade start. Once you are certain that everything you want to keep is in use, run:

$ docker system prune -a --volumes


To see the native Docker commands and other commands ade is executing, set the ECHO variable before running ade, e.g.

$ ECHO=1 ade start

Starting multiple ADE instances

When working on multiple projects with ADE configurations, it is desired to keep an instance of ADE running for each project. To run multiple instance, use the ADE_NAME environment variable to switch between the two instances.

Let’s say that there are two projects minimal-ade and AutowareAuto, cloned in ade-home:


It is recommended to keep separate ADE homes for each project; however, nothing prevents using the same ADE home for two projects.

Start the ADE instance for minimal-ade:

$ cd ~/ade-home/minimal-ade
$ export ADE_NAME=minimal
$ ade start

Then start the ADE instance for AutowareAuto:

$ cd ~/ade-home/AutowareAuto
$ export ADE_NAME=autoware
$ ade start

Now, in a new terminal, it is possible to select the ADE instance by setting ADE_NAME:

$ cd ~/ade-home
$ export ADE_NAME=minimal
$ ade enter
minimal$ # minimal ADE prompt

If ADE_NAME is not defined, the default name ade is used for a new environment.

In case the specified ADE is not found, ade enter offers an interactive prompt to select among the running environments. Press Enter to select the environment offered in brackets, or type minimal and press Enter to choose the other option:

$ cd ~/ade-home
$ ade enter
ERROR: An ADE instance named ade is not running.
Select one of {'autoware, minimal'} [autoware]:
Set ADE_NAME to suppress this prompt.
Entering autoware with following images:

The host name in the ADE container will match ADE_NAME, indicating the current ADE instance

Similarly, specific ADE instances can be stopped:

$ cd ~/ade-home
$ export ADE_NAME=autoware
$ ade stop
Stopping autoware


Starting multiple ADE works well when using the default network configuration; however, ADE instances may conflict if they use custom network configurations: