​
Overview

Blnk Cloud requires a running Blnk Core instance to work. You can host your own Core instance or deploy a managed Core instance from Blnk. For self-hosted instances, Blnk uses a Query Agent to establish a connection between your Core instance and Blnk Cloud.
The Query Agent is packaged in a docker container that you run on your machine or infrastructure.
  • Enhanced security: No need to expose database credentials or configure complex firewall rules.
  • Read-only access: Agent only requires SELECT permissions, ensuring data integrity.
  • Simplified setup: Eliminates network configuration complexity.
  • Reliable connection: Automatic reconnection and health monitoring.

​
Connect your self-hosted Core

1

Create an instance on Cloud

  1. In your Blnk Cloud workspace, go to Settings > Instances;
  2. Click Connect new instance;
  3. You’ll see the instance creation form.
2

Provide instance details

Fill in your instance information:
  1. Instance name: Choose a descriptive name (e.g., “Production”, “Staging”). This is the only required field;
  2. Core URL: Your Blnk Core instance URL (e.g., https://api.yourcompany.com);
  3. Core secret key: Your Blnk Core API secret key set in your blnk.json configuration file. You can leave this empty if you don’t have a secret key.
We use your Core URL and secret key to process actions in your workspace. Without them, your instance will be limited to read-only access.
Once done, submit the form.
3

Set up the Query Agent

After successfully creating your instance, Blnk generates a secure connection key to connect with your Query Agent.Next, you run the docker command to set up your Query Agent.
Replace the placeholder database URL with your actual connection string. The connection key is automatically generated and included in the command.
bash
docker run -d \
  --name blnk-agent \
  -e DB_URL="postgres://user:pass@host:port/db?sslmode=require" \
  -e CONNECTION_KEY="sk_live_..." \
  blnkfinance/query-agent:latest
The container name is generated automatically and is unique to your instance.
4

Verify connection

Return to your Blnk Cloud workspace:
  1. Check connection status: Navigate back to Settings > Instances;
  2. Verify agent status: Your instance should show as “Connected” with a green indicator.

​
Managing your Query Agent

​
Monitor connection health

To see how your connection is doing:
bash
# View real-time logs
docker logs -f blnk-agent-instance_563f3711-cbee-458c-8a1e-16aa610f81db

# Check container resource usage
docker stats blnk-agent-instance_563f3711-cbee-458c-8a1e-16aa610f81db

​
Update the Query Agent

To upgrade the Query Agent to the latest version:
bash
# Pull latest version
docker pull blnkfinance/query-agent:latest

# Stop and remove current container
docker stop blnk-instance_563f3711-cbee-458c-8a1e-16aa610f81db
docker rm blnk-instance_563f3711-cbee-458c-8a1e-16aa610f81db

# Restart with updated image (use your original configuration)
docker run -d \
      --name blnk-agent-instance_563f3711-cbee-458c-8a1e-16aa610f81db \
      -e DB_URL="postgres://blnk_readonly:secure_password@db.example.com:5432/blnk?sslmode=require" \
      -e CONNECTION_KEY="sk_live_xLsi30IVvgEZZLArji5OtM2t1F3mOmEpSaEbD0RqXII" \
      blnkfinance/query-agent:latest

​
Stop the Query Agent

To terminate your Query Agent:
bash
# Stop the container
docker stop blnk-agent-instance_563f3711-cbee-458c-8a1e-16aa610f81db

# Remove the container
docker rm blnk-agent-instance_563f3711-cbee-458c-8a1e-16aa610f81db

​
FAQs

Trouble connecting to your database locally?
  • If you’re running PostgreSQL inside Docker, use host.docker.internal as the host in your database URL.
  • If you’re running PostgreSQL directly on your machine, use localhost as the host in your database URL.
  • Ensure PostgreSQL is running and accessible.
  • Check that the port (default: 5432) is correct.
  • Verify your database credentials are correct.
Database connection failed?
  • Verify the database URL format is correct.
  • Ensure the database host is accessible from your Docker host.
  • Check that the database user has proper read permissions.
  • Verify network connectivity allows database connections.
  • Ensure SSL mode is correctly configured.
Docker container won’t start
  • Verify Docker is running: docker --version
  • Check if port conflicts exist: docker ps
  • Ensure environment variables are properly formatted.
  • Review Docker logs: docker logs blnk-agent --tail 50
Instance authentication failed
  • Verify the instance URL is accessible and responding.
  • Verify the instance secret key is correctly copied.
  • Ensure SSL certificate is valid if using HTTPS.
  • Confirm the instance is running and accepting connections.
  • Test instance connectivity: curl -H "Authorization: Bearer YOUR_SECRET_KEY" https://your-instance-url/health

​
Need help?

If you’re having trouble with Blnk Cloud, don’t hesitate to send us a message via email at support@blnkfinance.com or send us a message here.