Self-Hosted Instances

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.

Using Core v0.12.0 or lower? To improve speed and performance for your connection, read the optimization guide below.

Using the Query Agent, you get:

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: No need to configure network settings or firewall rules.
Reliable connection: Automatic reconnection and health monitoring.

Connect your self-hosted Core

Create an instance on Cloud

In your Blnk Cloud workspace, go to Settings → Instances;
Click Deploy an instance;
You’ll see the instance creation form.

Settings → Instances page showing the Deploy an instance button — Go to Settings → Instances and click Deploy an instance

Provide instance details

Fill in your instance information:

Instance name: Choose a descriptive name (e.g., “Production”, “Staging”). This is the only required field;
Core URL: Your Blnk Core instance URL (e.g., https://api.yourcompany.com):
- Make sure it is publicly accessible on the internet. If locally hosted, use a tunnel service like ngrok: ngrok http 5001 to create a public URL.
- If hosted on a private network, make sure to whitelist our IP addresses so that Cloud can communicate with your ledger:
  - 161.35.166.95
  - 161.35.171.250
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.

Instance creation form with instance name, Core URL, and secret key fields — Fill in your instance name, Core URL, and Core secret key, then create the connection

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.

Set up the Query Agent

Copy the Docker command from your Query Agent setup page and run it where it can reach your Core database.

Go to Settings → Instances.
Open the instance actions list or the instance details panel, then click View setup details.
Copy the Docker command from the Query Agent setup page. It already includes your connection key.
Replace <YOUR_DATABASE_URL> with your PostgreSQL connection string from blnk.json.

Opening View setup details and copying the Docker command from the Query Agent setup page — Open View setup details and copy the Docker command from the Query Agent setup page

Make sure to set the correct sslmode for your database. The database connection will fail without it.

If you’re running Blnk locally in Docker using the default blnk.json, see how to connect to your instance in Docker.

Verify connection

When the Query Agent is running, your instance shows Connected. Click the instance from your homepage, or go to Settings → Instances and click it, to open the details panel.

Instance details panel showing instance details — Click an instance from the homepage or Settings → Instances to open its details panel

Connecting to your database running inside your Docker container

To connect to your database running inside your Docker container:

Check the network of the postgres container

First, you need to identify which Docker network your database container is running on.

docker inspect postgres | grep NetworkMode

This command will show you the network name that your PostgreSQL container is using.

Run the Query Agent on the same network

Next, run the Query Agent container on the same network as your database container.

docker run -d \
  --network <network-name> \
  -e DB_URL="postgres://username:password@postgres:5432/database_name?sslmode=disable" \
  -e CONNECTION_KEY="sk_live_..." \
  blnkfinance/query-agent:latest

Make sure to replace:

<network-name> with the network name from the previous step, e.g. --network blnk_default.
Update the DB_URL with your actual database connection details. You can find it in your default blnk.json configuration file.
Important: Since you’re running the Query Agent in the same network as your Core docker image, keep postgres as the host in your connection string. This is the service name of your PostgreSQL container.
Replace sk_live_... with your actual connection key from the connection setup page on Cloud.

Edit your instance

Go to Settings → Instances, open the instance actions list, and click Edit instance. You can change the name, Core URL, or Core secret key.

Core URL

Make sure the Core URL is publicly accessible on the internet. If locally hosted, use a tunnel service like ngrok: ngrok http 5001 to create a public URL.

If hosted on a private network, whitelist Cloud IPs so Cloud can reach your ledger.

Core secret key

The Core secret key is created and set by you in your Blnk configuration. Provide the secret key used in your config. If not set, leave empty.

Managing your query agent

View the setup guide

Open the instance actions list or the instance details panel and click View setup details. You’ll see your connection details, agent connection key, and connection status.

Query Agent setup guide page showing connection details, agent key, and Connected status — Open View setup details to see your connection key, setup steps, and connection status

Monitor connection health

To see how your connection is doing:

bash

# Health check endpoint (returns 200 OK when live)
curl -X GET http://localhost:9090/live

The agent listens on port 9090 by default. To change the internal HTTP port, set the HTTP_PORT environment variable.

docker run -d \
  -e HTTP_PORT=9090 \
  -e DB_URL="postgres://username:password@host:port/database_name?sslmode=disable" \
  -e CONNECTION_KEY="sk_live_..." \
  blnkfinance/query-agent:latest

View logs and resource usage

bash

# View real-time logs
docker logs -f <container-name>

# Check container resource usage
docker stats <container-name>

Update the Query Agent

To upgrade the Query Agent to the latest version:

bash

# Pull latest version
docker pull blnkfinance/query-agent:latest

# Stop current container
docker stop <container-name>

# Restart with updated image (use your original configuration)
docker run -d \
      --name <container-name> \
      -e DB_URL="postgres://username:password@host:port/database_name?sslmode=disable" \
      -e CONNECTION_KEY="sk_live_..." \
      blnkfinance/query-agent:latest

If you previously customized the agent’s HTTP port, remember to include -e HTTP_PORT=<port> and publish the same container port with -p <host-port>:<port> when restarting.

Stop the Query Agent

To terminate your Query Agent:

bash

# Stop the container
docker stop <container-name>

Delete an instance

Open the actions list and click Delete instance. Follow the instructions in the modal to complete the action.

This action is irreversible.

Deleting a self-hosted instance from the actions menu with the confirmation modal — Open the actions list and click Delete instance

Performance optimization for Core 0.12.1 or lower

If you’re running Blnk Core version 0.12.1 or lower, you need to apply database indexes to significantly improve query performance and speed up your Blnk Cloud workspace.

If you’re on later versions, these indexes are automatically included and you don’t need to take any action.

Connect to your PostgreSQL database

Connect to your Core database using your preferred PostgreSQL client or command line:

bash

psql -h your-host -p 5432 -U your-user -d your-database

Apply the database indexes

Run the following SQL commands to create the required indexes:

CREATE INDEX CONCURRENTLY IF NOT EXISTS
blnk_transactions_currency_created_at_idx
ON blnk.transactions (currency, created_at DESC);

CREATE INDEX CONCURRENTLY IF NOT EXISTS
blnk_transactions_created_at_source_idx
ON blnk.transactions (created_at, source);

CREATE INDEX CONCURRENTLY IF NOT EXISTS
blnk_transactions_created_at_destination_idx
ON blnk.transactions (created_at, destination);

CREATE INDEX CONCURRENTLY IF NOT EXISTS
blnk_balances_created_at_idx
ON blnk.balances (created_at DESC);

CREATE INDEX CONCURRENTLY IF NOT EXISTS blnk_txn_created_at_not_queued_idx
ON blnk.transactions (created_at DESC)
WHERE status <> 'QUEUED';

CREATE INDEX CONCURRENTLY IF NOT EXISTS blnk_txn_currency_created_at_desc_idx
ON blnk.transactions (currency, created_at DESC)
INCLUDE (precision);

CREATE INDEX CONCURRENTLY IF NOT EXISTS blnk_identity_created_at_idx
ON blnk.identity (created_at DESC);

CREATE INDEX CONCURRENTLY IF NOT EXISTS blnk_balances_identity_id_idx
ON blnk.balances (identity_id);

CREATE INDEX CONCURRENTLY IF NOT EXISTS blnk_ledgers_created_at_idx
ON blnk.ledgers (created_at DESC);

CREATE INDEX CONCURRENTLY IF NOT EXISTS blnk_balances_ledger_id_idx
ON blnk.balances (ledger_id);

CREATE INDEX CONCURRENTLY IF NOT EXISTS blnk_balances_currency_identity_id_idx
ON blnk.balances (currency, identity_id);

CREATE INDEX CONCURRENTLY IF NOT EXISTS blnk_identity_country_created_at_idx
ON blnk.identity (country, created_at DESC);

CREATE INDEX IF NOT EXISTS idx_transactions_status ON blnk.transactions(status);
CREATE INDEX IF NOT EXISTS idx_transactions_currency ON blnk.transactions(currency);
CREATE INDEX IF NOT EXISTS idx_transactions_source ON blnk.transactions(source);
CREATE INDEX IF NOT EXISTS idx_transactions_destination ON blnk.transactions(destination);
CREATE INDEX IF NOT EXISTS idx_transactions_parent_transaction ON blnk.transactions(parent_transaction);

CREATE INDEX IF NOT EXISTS idx_transactions_meta_data ON blnk.transactions USING gin(meta_data);

The indexes will be created and applied to your database. This may take a few moments depending on your database size.

Deploy components in the same region

To see faster improvements across Core and Cloud, follow these regional deployment recommendations:

Keep Core and the PostgreSQL database (and other services) in the same region: Deploy your Core instance, PostgreSQL database, and any other related services within the same geographical region to minimize latency.
Keep the Query Agent in the same region as the database: Ensure your Query Agent is deployed in the same region as your PostgreSQL database to reduce query latency and improve connection speed.

Verify the improvements

After applying the indexes, refresh your Blnk Cloud workspace to experience improved performance when loading balances, transactions, and other data.

FAQs

Trouble connecting to your database locally?

If you’re running PostgreSQL inside Docker (on a Mac/Linux), use host.docker.internal as the host in your database URL.
For Windows, run the Query Agent container on the same network as your database container. Learn more
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?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.

Start Here

Instances

Ledgers

Balances

Transactions

Identities

Reconciliation

Filters & Views

Alerts

Insights

Settings

Integrations

Connect your self-hosted Core

Connecting to your database running inside your Docker container

Edit your instance

Managing your query agent

Delete an instance

Performance optimization for Core 0.12.1 or lower

FAQs

Need help?

​Connect your self-hosted Core

​Connecting to your database running inside your Docker container

​Edit your instance

​Managing your query agent

​Delete an instance

​Performance optimization for Core 0.12.1 or lower

​FAQs

​Need help?

Connect your self-hosted Core

Connecting to your database running inside your Docker container

Edit your instance

Managing your query agent

Delete an instance

Performance optimization for Core 0.12.1 or lower

FAQs

Need help?