Agent Runtime Options

The Coordimap agent reads a YAML configuration file at startup, expands environment variables, connects to configured data sources, and sends discovered infrastructure metadata to Coordimap. Use this page when you need to run, debug, or operationalize the agent runtime.

Default Configuration File

By default, the agent looks for a config.yaml file near the executable.

For explicit deployments, pass the file path with --config:

./agent --config ./config.yaml

For Docker deployments, mount the file and pass the path inside the container:

docker run --rm \
  -v "$(pwd)/config.yaml:/config.yaml:ro" \
  -e COORDIMAP_API_KEY="YOUR_API_KEY" \
  coordimap/coordimap-agent:v1.2.7 \
  --config /config.yaml

Debug Mode

Use --debug while validating a new configuration or investigating startup issues.

./agent --debug --config ./config.yaml

Do not leave overly verbose logs enabled in production unless you need them for a temporary investigation.

Environment Variable Substitution

The public example configuration uses environment variable placeholders such as ${COORDIMAP_API_KEY}, ${AWS_ACCESS_KEY_ID}, and ${POSTGRES_PASSWORD}.

Example:

coordimap:
  api_key: ${COORDIMAP_API_KEY}
  data_sources:
    - type: postgres
      data_source_id: postgres-primary
      config:
        - name: db_pass
          value: ${POSTGRES_PASSWORD}

Set those variables in the runtime environment before starting the agent.

Production Credential Handling

Use the least-sensitive option available for each environment.

Recommended approaches:

• IAM roles for AWS runtimes such as EC2 or EKS
• metadata-service authentication for GCP runtimes when in_cloud is supported
• Kubernetes Secrets for in-cluster deployments
• environment variables injected by a secret manager
• read-only database users for PostgreSQL, MySQL, MariaDB, and MongoDB

Avoid committing API keys, access keys, database passwords, or service account JSON files to source control.

Startup Checklist

Before restarting the agent, confirm that:

1. coordimap.api_key is set or resolvable from the environment.
2. Each data source has the correct type.
3. Each data source has the expected Coordimap connector identifier.
4. Each data source has a stable upstream scope_id.
5. Credential files and mounted paths exist in the agent runtime.
6. The agent runtime can reach the target APIs or databases.
7. crawl_interval values are reasonable for the environment.

Common Runtime Failures

Source References

• Coordimap Agent Repository
• Coordimap Agent Example Configuration
• Coordimap Agent Config Template

FAQ

How do I choose the agent configuration file?

Pass the path with --config. This is more explicit than relying on default file lookup and is recommended for Docker, Kubernetes, and production deployments.

How do I troubleshoot a new Coordimap agent setup?

Start with one data source, run the agent with --debug, confirm credentials and network access, then verify that the data source uses the correct scope_id.

Can I keep secrets in config.yaml?

Avoid storing secrets directly in config.yaml. Use environment variables, Kubernetes Secrets, IAM roles, service accounts, or a secret manager.