Agent Getting Started

From zero to a running BoltPipeline Agent. Bootstrap, configure credentials, verify, and start — in about 20 minutes.

Before you begin

Prerequisites

Have these ready before downloading the bootstrap package. The bootstrap token is time-limited — don't start that clock until you're ready.

Docker

Docker Engine 24+ and docker-compose v2. The agent runs as a container.

Database account

Three database users provisioned with appropriate read, write, and DDL privileges. See the Credentials guide.

Secret manager access

Credentials stored in your secret manager (AWS Secrets Manager, HashiCorp Vault, or Azure Key Vault).

BoltPipeline Console access

Operator or Admin role required to download the bootstrap package from the Agents page.

Read the whole guide before downloading the bootstrap package. The bootstrap token is time-limited. Complete all prerequisite steps first, then download and run immediately.

1Step 1

Download the bootstrap package

The bootstrap package binds your agent to a specific environment. Each environment requires its own package.

1
In the BoltPipeline Console, navigate to Agents.
2
Click Download Bootstrap Package for the target environment (e.g., Development).
3
Save the downloaded package. It contains the identity files needed for registration.

The package contains:

•A one-time registration token (time-limited, single-use)
•A trust certificate for secure agent-to-platform communication

Do not download until you are ready to start the agent immediately. The bootstrap token expires quickly. If it expires, generate a new one from the Console — the old package is single-use and cannot be reused.

2Step 2

Set up directories

The agent uses separate directories for identity material, logs, and an offline work queue. Follow the setup instructions included with your bootstrap package to create the required directory structure on the agent host.

Directory layout

•Identity directory — bootstrap files and agent identity material
•Logs directory — agent logs and execution artifacts
•Spool directory — offline task queue (used when connectivity is interrupted)

Extract the bootstrap package into the identity directory for the target environment. Repeat for each environment you want to run. Each environment's bootstrap files go into its own subdirectory.

3Step 3

Configure credentials

The agent needs credentials for three database users. Store your credentials in a supported secret manager and reference them in the agent configuration.

Secret manager (recommended)

All envs

Recommended for all environments. Credentials are fetched at runtime from your secret manager. No sensitive values are stored on disk.

Local file (non-production only)

dev / lab only

Low-friction option for developers during initial setup. Reads a local credential file from the host. Blocked in production environments.

See Credentials for the full setup instructions and supported secret manager integrations.

4Step 4

Configure the agent

Configure your agent using the settings provided in your Console. The configuration file specifies your target environment, credential references, and operational settings. No sensitive values go in this file — only references to your secret manager.

Key configuration settings

•Target environment — dev, lab, int, or prd
•Database users — secret manager references for reader, pipeline, and DDL admin users
•Warehouse and scratch settings — warehouse name and scratch schema for profiling
•Logging — log level and format (text for dev, JSON for production)

See Configuration for the full reference of all available settings.

5Step 5

Build the agent image

Build the Docker image using the build script included in the agent repository. You only need to rebuild when updating the agent version.

Follow the build instructions provided in your agent repository. The image must be built before running docker-compose.

6Step 6

Verify with system-readiness

Before starting the agent, run the pre-flight check. This confirms all credentials resolve, database connectivity works, and identity files are in place — without starting the polling loop.

The system-readiness command checks:

✓Configuration file is valid and all required fields are present
✓All database users can connect successfully
✓Identity files are present and valid
✓Trust certificates are readable

If any check fails, see system-readiness for detailed failure guidance.

7Step 7

Start the agent

Start the agent using docker-compose. The agent will bootstrap on first run.

# Start the agent for your target environment
docker compose up agent-<env>

# Follow logs
docker compose logs -f agent-<env>

# Or start detached
docker compose up -d agent-<env>

To stop:

docker compose down

If you are using a secret manager for database credentials, ensure the agent container has the necessary permissions to access your secrets at runtime. If you are using file-based credentials (non-production only), secret manager access is not required.

After start

What happens next

Bootstrap (first run only)

The agent uses its bootstrap token to register with the BoltPipeline platform over a secure mTLS connection. During registration, the agent generates its own identity keypair and receives a signed client certificate. The bootstrap token is consumed and cannot be reused.

Session establishment

The agent establishes a secure session with the platform and begins its operational cycle. Certificate rotation is handled automatically.

Poll loop

The agent enters its steady-state loop: it checks platform health, sends telemetry, and polls for work. When a task arrives — Discovery, Profile, Certify, Operate, or DDL Deploy — the agent executes it against your database and submits the result.

Once registered, the agent runs unattended.

Offline mode is supported — if the platform is unreachable, tasks are queued locally and flushed when connectivity resumes. Certificate rotation is handled automatically.

Need help?

Email us at support@boltpipeline.ai