Install and Run Agents

The agent software runs on your own infrastructure. The token you provide when starting the agent assigns it to a Terraform Cloud agent pool.

Operational Considerations

Agents do not guarantee a clean working environment per Terraform execution. Each execution occurs in its own temporary directory with a clean environment, but references to absolute file paths or other machine state may cause interference between Terraform executions. We strongly recommend that you write your Terraform code to be stateless and idempotent. You may also want to consider using single-execution mode to ensure your agent only runs a single workload.

Run Multiple Agents

You may choose to run multiple agents within your network, up to the organization's purchased agent limit. If there are multiple agents available within an organization, Terraform Cloud selects the first available agent within the target pool.

Each agent process runs a single Terraform run at a time. Multiple agent processes can be concurrently run on a single instance, license limit permitting.

Resilience

The agent distributes as a standalone binary that runs on any supported system. By default, the agent runs in the foreground as a long-running process that continuously polls for workloads from Terraform Cloud. An agent process may terminate unexpectedly due to stopping the process forcefully, power cycling the host machine, and other methods. We strongly recommend pairing the agent with a process supervisor to ensure that it automatically restarts in case of an error.

Download and Install the Agent

Download the latest agent release, the associated checksum file (.SHA256sums), and the checksum signature (.sig).
Verify the integrity of the downloaded archive, as well as the signature of the SHA256SUMS file using the instructions available on HashiCorp's security page.
Extract the release archive. The unzip utility is available on most Linux distributions, and you can invoke it by running unzip <archive file>. The unzip command extracts two individual binaries (tfc-agent and tfc-agent-core). These binaries must reside in the same directory for the agent to function properly.

Updates

By default, the agent automatically updates itself to the latest minor version. Administrators must update the host operating system and all other installed software.

To customize this update behavior, pass the flag -auto-update or set the environment variable TFC_AGENT_AUTO_UPDATE to one of the following settings.

Update Setting	Behavior
`minor`	Matches the default behavior, automatically updates the agent to the latest minor version.
`patch`	The agent only updates to the newest patch version, new minor versions require a manual update.
`disabled`	Disables automatic updates, all updates are manual.

Start the Agent

To start the agent and connect it to a Terraform Cloud agent pool:

Retrieve the token from the Terraform Cloud agent pool you want to use.
Set the TFC_AGENT_TOKEN environment variable.
(Optional) Set the TFC_AGENT_NAME environment variable. This name is for your reference only. The agent ID appears in logs and API requests.

export TFC_AGENT_TOKEN=your-token
export TFC_AGENT_NAME=your-agent-name
./tfc-agent

Once complete, your agent and its status appear on the Agents page in the Terraform Cloud UI. Workspaces can now use this agent pool for runs. Refer to Configure Workspaces to Use the Agent for details.

Optional Configuration: Run an Agent Using Docker

Alternatively, you can use our official agent Docker container to run the agent.

docker pull hashicorp/tfc-agent:latest
docker run -e TFC_AGENT_TOKEN=your-token -e TFC_AGENT_NAME=your-agent-name hashicorp/tfc-agent

This Docker image executes the tfc-agent process as the non-root tfc-agent user. For some workflows, such as workflows requiring the ability to install software using apt-get during local-exec scripts, you may need to build a customized version of the agent Docker image for your internal use.

FROM hashicorp/tfc-agent:latest

USER root

# Install sudo. The container runs as a non-root user, but people may rely on
# the ability to apt-get install things.
RUN apt-get -y install sudo

# Permit tfc-agent to use sudo apt-get commands.
RUN echo 'tfc-agent ALL=NOPASSWD: /usr/bin/apt-get , /usr/bin/apt' >> /etc/sudoers.d/50-tfc-agent

USER tfc-agent

An image customized in this way permits installation of additional software via sudo apt-get.

Optional Configuration: Single-Execution Mode

You can also configure the agent to run in single-execution mode, which ensures that the agent only runs a single workload, then terminates. You can use this configuration in combination with Docker and a process supervisor to ensure a clean working environment for every Terraform run.

To use single-execution mode, start the agent with the -single command line argument.

Stop the Agent

Important: We strongly recommend that you only terminate the agent using one of these methods. Abruptly terminating an agent by forcefully stopping the process or power cycling the host does not let the agent deregister and results in an Unknown agent status. Abrupt termination may cause further capacity issues. Refer to capacity issues for details.

The agent maintains a registration and a liveness indicator within Terraform Cloud during the entire course of its runtime. When an agent retires, it must deregister itself from Terraform Cloud. The agent deregisters automatically as part of its shutdown procedure in the following scenarios:

You enter Ctrl-C in an interactive terminal.
The agent process ID receives one of SIGINT, SIGTERM, or SIGQUIT. It is important to send only one signal. The agent interprets a second signal as forceful termination signal exits immediately.

After initiating a graceful shutdown by either of these methods, the terminal user or parent program should wait for the agent to exit. The amount of time this exit takes depends on the agent's current workload. The agent waits for any current operations to complete before deregistering and exiting.