run
Start the BoltPipeline Agent. The agent bootstraps, opens a session, and enters the steady-state poll loop.
Usage
Starting the agent
Start the agent using docker-compose. The agent reads its configuration file, resolves credentials, and enters the operational loop.
# Start the agent for your environment
docker compose up agent-<env>
# Start detached
docker compose up -d agent-<env>Configuration resolution
The agent resolves its configuration from a CLI flag, an environment variable, or a default file in the working directory — in that order of priority. See the Configuration guide for full details.
Startup
Startup sequence
On startup the agent runs these steps before entering the poll loop. Each step must succeed — failure at any step halts startup with a clear error.
Load and validate configuration
The agent reads the configuration file, validates all required fields, rejects unknown keys, type-checks values, and merges platform defaults.
Resolve database credentials
Each database user resolves its credential reference from the configured secret manager or local file. Production environments block file-based credentials at this step.
Register identity (first run only)
If the agent is unregistered, it performs initial registration with the BoltPipeline platform — generating its identity keypair and receiving a signed client certificate.
Establish session
The agent establishes a secure session with the platform and handles any pending certificate rotation.
Enter operational loop
The agent enters the health check, heartbeat, and task poll cycle. From this point on, the agent runs until stopped.
Steady state
The poll loop
Once started, the agent runs a continuous operational loop. The cadence is determined by platform policy — the agent adapts its poll interval based on backoff hints.
Platform connectivity
Telemetry and sync
Request next task
Health check
Lightweight platform health probe. If the platform is unreachable, the agent enters offline mode and queues work locally.
Heartbeat
Sends telemetry: agent version, uptime, and execution metrics. The platform uses this to track agent health and detect drift.
Task poll
Requests the next task from the platform. If a task is assigned (Discovery, Profile, Certify, Operate, or DDL Deploy), the agent executes it and submits the result.
Offline mode: If the platform is unreachable, the agent queues completed task results locally and flushes them automatically when connectivity resumes. The agent never drops results.
Observability
Log output
Log format is controlled by the log_format setting in your configuration file.
Human-readable text format. Suitable for local development and debugging.
Structured JSON format suitable for log aggregation (CloudWatch, Splunk, Datadog). All fields are machine-parseable. PII and credentials are redacted in all log formats.
Operations
Stop and restart
# Stop the agent
docker compose stop agent-<env>
# Restart (picks up config changes)
docker compose restart agent-<env>
# Stop all agents
docker compose down
# Tail live logs
docker compose logs -f agent-<env>Restart is safe. The agent resumes its session on restart — it does not re-bootstrap. Bootstrap only happens once during initial registration. Subsequent restarts use the stored identity.
Need help?
Email us at support@boltpipeline.ai