@visio/agent (visio-agent)

Zero-install, zero-trust local database tunneling daemon and CLI agent for Visio.

Visio Agent is a lightweight local bridge that connects your local or private PostgreSQL databases (127.0.0.1:5432) to the Visio Web Application. It creates an ephemeral, encrypted tunnel so you can visualize schemas, run AI-assisted queries, and monitor database telemetry without exposing local ports or uploading database credentials to remote servers.

⚡ Quick Start

Option 1: Zero-Install Execution (Recommended)

Run directly with npx without pre-installing:

npx visio-agent

Option 2: Global Installation

Install globally via npm or pnpm:

npm install -g visio-agent
# or
pnpm add -g visio-agent

Then start the agent anytime:

visio-agent

The agent will initialize on http://127.0.0.1:4567 and prepare local database discovery.

🏗️ How It Works

┌───────────────────────────────┐
│     Developer Machine         │
│                               │
│  ┌─────────────────────────┐  │         Encrypted Cloudflare Tunnel       ┌─────────────────────────┐
│  │   PostgreSQL Database   │  │ <=======================================> │      Visio Web App      │
│  │    (127.0.0.1:5432)     │  │          (*.trycloudflare.com)          │  (visio-fe / Next.js)  │
│  └────────────▲────────────┘  │                                           └─────────────────────────┘
│               │               │
│  ┌────────────┴────────────┐  │
│  │       visio-agent       │  │
│  │   (NestJS Daemon :4567) │  │
│  └─────────────────────────┘  │
└───────────────────────────────┘

1. Local Auto-Discovery: visio-agent connects locally to 127.0.0.1:5432 to inspect local database instances.
2. Secure Tunnel Creation: On demand, visio-agent launches an ephemeral Cloudflare Tunnel (*.trycloudflare.com). No incoming firewall ports need to be opened.
3. AES-256 Session Encryption: Credentials and connection parameters are encrypted with AES-256 and stored in Redis with sliding TTL expiration.
4. Data Isolation: Database passwords never leave your machine; queries are proxied and executed strictly inside visio-agent.

🚀 Features

• Zero-Trust Security: No static public IP or port forwarding required.
• Auto DB Discovery: Scans local PostgreSQL instances and lists available databases.
• Database Management: Create, drop, or rename databases directly through the UI.
• Relational Schema Inspection: Inspect tables, columns, primary keys, and foreign key relations.
• Telemetry Streaming: Real-time stats on active pool connections and query execution latency.
• Cross-Platform: Packageable as standalone binaries for Linux, macOS, and Windows.

⚙️ Environment Variables

Customize agent behavior using environment variables or a .env file:

| Variable | Default | Description | | :--- | :--- | :--- | | PORT | 4567 | Local HTTP port for the agent server | | DB_SESSION_KEY | (32-byte default key) | AES-256 secret key for session payload encryption | | REDIS_HOST | 127.0.0.1 | Redis host for session caching | | REDIS_PORT | 6379 | Redis port |

🔌 API Endpoints Summary

| Endpoint | Method | Description | | :--- | :--- | :--- | | /health | GET | Returns agent status, version, and active tunnel URL | | /db/discover | POST | Discovers available local PostgreSQL databases | | /db/manage | POST | Perform database CRUD operations (create, drop, rename) | | /bridge/create | POST | Spawns a Cloudflare tunnel bridge for remote connection |

📦 Building Standalone Executables

To package the agent into single-file binary executables without Node.js runtime dependencies:

npm run build:package

Binary outputs will be saved in ./bin/:

• bin/visio-agent-linux-x64
• bin/visio-agent-macos-x64
• bin/visio-agent-win-x64.exe

📄 License

MIT License © 2026 Visio Team