Local agents

A local agent is a small process you run on your own machine, server, or cluster. It holds the database credentials locally, executes queries there, and returns only result sets to Chartizer.

When to use one

Private databases

The database listens on localhost, a private VPC, or behind a VPN — unreachable from Chartizer Cloud.

Policy constraints

Credentials may not be stored by a third party, even encrypted.

Cloud is fine for most teams

An agent adds a process to operate. If your database is already internet-reachable and you are comfortable with encrypted credential storage, use the Cloud runtime.

Install

Bash

curl -fsSL https://get.chartizer.com/agent | sh
chartizer-agent login
chartizer-agent start

Bash

docker run -d --name chartizer-agent \
  --restart unless-stopped \
  -e CHARTIZER_AGENT_TOKEN="$CHARTIZER_AGENT_TOKEN" \
  -v chartizer-agent:/var/lib/chartizer \
  chartizer/agent:latest

docker-compose.yml
services:
  chartizer-agent:
    image: chartizer/agent:latest
    restart: unless-stopped
    environment:
      CHARTIZER_AGENT_TOKEN: ${CHARTIZER_AGENT_TOKEN}
      CHARTIZER_AGENT_NAME: eu-prod-agent
    volumes:
      - chartizer-agent:/var/lib/chartizer

volumes:
  chartizer-agent:

/etc/systemd/system/chartizer-agent.service
[Unit]
Description=Chartizer local agent
After=network-online.target

[Service]
Type=simple
User=chartizer
Environment=CHARTIZER_AGENT_TOKEN=…
ExecStart=/usr/local/bin/chartizer-agent start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Pair it with your team

Create an agent token

In Chartizer, open Settings → Agents → New agent. Copy the token — it is shown once.

Start the agent with the token

Pass it as CHARTIZER_AGENT_TOKEN, or run chartizer-agent login and paste it.

Confirm it reports Online

The agent appears in the connection dialog’s Runtime section with an Online badge. If it stays offline, check outbound access to agent.chartizer.com:443.

Select it when creating a source

Choose Add local agent instead of Cloud, then enter the database details as the agent sees them — localhost and private hostnames now work.

Networking

The agent makes outbound connections only. No inbound ports, no firewall exceptions.

Direction	Destination	Port	Purpose
Outbound	`agent.chartizer.com`	443	Control channel and results, TLS
Outbound	your database	e.g. 5432	Queries, inside your network

Verify outbound connectivity

chartizer-agent doctor

What Chartizer receives

Query results, schema metadata, and agent health. Never the credentials — those stay in the agent’s local store.

Operating

Task	Command
Status	`chartizer-agent status`
Live logs	`chartizer-agent logs -f`
Connectivity check	`chartizer-agent doctor`
Update	`chartizer-agent update`
Rotate token	`chartizer-agent login` with a new token

A stopped agent stops its sources

Every source bound to an agent fails while it is offline. Run it somewhere durable — a server or container host, not a laptop that sleeps.

Agent shows Offline right after starting

Outbound 443 to agent.chartizer.com is blocked, or the token was already used by another agent. Run chartizer-agent doctor.

Agent online but the database still times out

The agent reaches Chartizer but not your database. From the agent host, test the exact host and port with psql or nc -vz host 5432.

Moving a source from Cloud to an agent

Open the source, change Runtime to the agent, and re-enter the password. Datasets and mappings are preserved.