Skip to main content

Cloud Agents


Some features require Atlas Cloud to connect to your database. As it is uncommon for databases to be directly accessible from the internet, you can run Atlas Agents in your database's network to facilitate this communication. Agents register themselves via credentials against your Atlas Cloud account and continuously poll it for work.

The following features require an Atlas Agent installed in your databases network:

  • Drift Detection
  • Cloud mediated deployments (coming soon)
  • Schema monitoring and auditing (coming soon)

Drift Detection is currently only available in a paid subscription.

Create an Agent

To create an Agent, head over to the general settings and click on the "Agents" tab.


Only admins can create Agents. Ensure you have sufficient permissions before proceeding.

Screenshot Example

Pick a name for your Agent and hit Create Agent.

Screenshot Example

Connect the Agent

Now that we have created an Agent in your Atlas Cloud account, we can run an Agent process. This is typically done by running it in the same network as our target database. To authenticate against your Atlas Cloud account, a token will be created which you will need to provide the Agent with. Store this token in a secure place, as you won't be able to see it again. If needed, you can always create a new one later.

Screenshot Example

To start the Agent and let it poll work from Atlas Cloud, simply follow the instructions shown. Currently, Ariga provides two builds, a docker image and a linux amd64 binary. All you need to provide the Agent with is a token to authenticate against Atlas Cloud.

If you want to use the Docker image, run the following:

docker run -e ATLAS_TOKEN <your atlas token> arigaio/atlas-agent

If the Agent has access to the internet and can reach Atlas, you should see a success message.

Screenshot Example

Now the Agent is running and can connect to Atlas. However, in order to connect to your databases, it needs to know how to obtain valid credentials and how to use them.

Database Credentials

Since we want the Agent to connect to our database on behalf of Atlas, it needs to know how to access it. For this we can assign an Agent multiple database connections. Either click the Set up Database Connection or select the Database Connections tab and hit Create Connection.


You can only create a connection with an actively running Agent. If there is no Agent selectable in the dropdown, ensure the Agent binary is still running and has access to the cloud.

Fill out the form with the connection details to your database.

Screenshot Example

AWS RDS databases offer to obtain a short-lived token using an IAM role to authenticate against an RDS instance.

  1. Enable IAM Authentication for your database. For instructions on how to do this, see the AWS documentation.

  2. Create an IAM role with the "rds-db:connect" permission for the specific database and user. For instructions on how to do this, see the AWS documentation.

All other info required to obtain a token is derived from the RDS endpoint you define in the connection modal.

To ensure the credentials are correct, Atlas will check if the credentials are working before we can save them. Hit the Test Connection button and wait. It can take a few seconds before the Agent will pick up the job and check the connection to the database.

If all goes well, we should see a message telling us that Atlas was able to connect to our database through the Agent.

Screenshot Example

Drift Detection

Once Atlas can connect to your database, it can start monitoring your schema and warn you if it detects a drift between your migration directory and its deployment. In the migration directory overview, click on Enable Drift Detection. You'll be asked which database connection the deployments are reachable on.

Screenshot Example

Once enabled, Atlas will run drift detection jobs twice a day. If there is a drift, Atlas will provide you with detailed information about the drift, including an ERD, HCL diff and SQL statements required to fix the drift.


Do not apply the SQL blindly to fix the drift. It is potentially destructive.

Screenshot Example


You can instruct Atlas to notify you if there is a drift. Atlas supports various channels, such as email, Slack, Workplace or by a plain webhook.

Screenshot Example