Available on all Cloud plans.

​
Overview

You need to connect a running Blnk Core instance to start using Cloud to work with your financial data. Blnk uses a secure Query Agent that establishes a connection between your instance and Cloud without exposing your database credentials directly. The Query Agent handles all database queries internally while maintaining strict read-only access, providing:
  • 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.

Install Blnk Core

Learn how to install and deploy a Blnk Core instance.

Have trouble installing?

Contact our support team if you need help with deploying a Blnk Core instance.

​
Prerequisites

Before you begin, ensure you have:
  • Docker installed and running on your system;
  • A running Blnk Core instance in your environment;
  • Database credentials with read permissions;
  • Your Blnk Core instance URL and secret key.
Not a developer? We recommend doing this with a developer or your engineering team for seamless implementation.

​
1. Create your instance

First, you need to create an instance connection in your Blnk Cloud workspace. This will generate a secure connection key that the Query Agent will use to establish the connection.
1

Navigate to instance creation

  1. In your Blnk Cloud workspace, go to Settings > Instances;
  2. Click Connect new instance;
  3. You’ll see the instance creation form.
Blnk Cloud instance creation form showing fields for instance name, Core URL, and Core secret key with Create connection button
2

Provide instance details

Fill in your instance information:
  • Instance name: Choose a descriptive name (e.g., “Production”, “Staging”);
  • Core URL: Your Blnk Core instance URL (e.g., https://api.yourcompany.com);
  • Core secret key: Your Blnk Core API secret key.
We use these credentials to perform back-office actions in your Core instance. Without them, your instance will be limited to read-only access.
3

Generate connection key

  1. Click Create connection to generate your secure connection key;
  2. Copy the generated connection key — you’ll need this for the Query Agent setup;
  3. Keep this key secure as it provides access to your instance data.
Blnk Cloud interface showing Query Agent connection status with waiting indicator and connection key display

​
2. Connect your instance

Now that you have your connection key, deploy the Query Agent to establish the secure connection between your database and Blnk Cloud.
1

Launch Docker

First, verify that Docker is installed and running on your system:
bash
# Check if Docker is running
docker --version
If Docker is working correctly, you should see version information and a list of running containers (which may be empty).
If Docker isn’t installed:
2

Prepare your database URL

Create your PostgreSQL connection string using this format:
psql
postgres://<user>:<password>@<host>:<port>/<db-name>?sslmode=
If you’re running PostgreSQL locally within a docker container, use host.docker.internal as the host.
3

Run the connection agent

Execute the Docker command with your configuration. Replace the placeholder values with your actual database URL and connection key:
bash
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
The container name is generated automatically and is unique to your instance.

​
Verify the agent is running

bash
# Check container status
docker ps | grep blnk-agent

# View recent logs
docker logs blnk-agent-instance_563f3711-cbee-458c-8a1e-16aa610f81db --tail 20
You should see logs indicating successful database connection and WebSocket connection to Blnk Cloud.
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;
  3. Test the connection: The system will automatically verify that the Query Agent is communicating properly.
Blnk Cloud interface showing connected Query agent
Once the agent connects successfully, your Cloud workspace will be initialized and you can start exploring your financial data in the dashboard.

​
Troubleshooting

​
Managing your connection agent

1

Monitor connection health

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
2

Update the connection agent

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
3

Stop the connection 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

​
Next steps

Explore your data

Navigate your workspace and start analyzing your financial data.

Set up compliance monitoring

Configure automated compliance monitoring and anomaly detection.

Manage team access

Invite team members and configure workspace permissions.

Configure notifications

Set up alerts for suspicious activities and threshold breaches.

​
Need help?

Let’s help you get started with Cloud! Whether you’re setting up your first workspace or adding Cloud to your existing tools, our team is here to help you succeed. Contact our Support team to get answers and expert guidance on making the most of Cloud.