Getting Started
Overview Quick Start ConfigurationCommands
Service Management Produce Consume ExposeFeatures
Secret Keys Encryption Environment VariablesExamples
Database Access Web Services Folder SharingComplete reference for the Vemari CLI binary and all its features.
Vemari is a lightweight TCP tunneling system that enables secure access to remote services through a central proxy server. It operates in three modes and supports both command-line flags and configuration file management:
Expose a local service (database, web server, etc.) to be accessible through the proxy via STCP.
Access a remote service through a local port, as if it were running on your machine.
Expose a local HTTP service publicly with a custom subdomain at vemari.one. Automatically secured with HTTPS.
Vemari can be used in two ways: with command-line flags for quick one-off connections, or with a configuration file for managing multiple services. By default, Vemari connects to a proxy server. You can override this with the -proxy flag or in your configuration file.
Configuration File Mode
For managing multiple services, create a vemari.toml file next to the binary and use commands like vemari list, vemari run, etc. See the Configuration section for details.
$ vemari -produce mydb -target localhost:5432$ vemari -consume mydb -local 15432Now connect to localhost:15432 and traffic will be tunneled to the remote database.
Vemari supports configuration via a TOML file named vemari.toml placed next to the binary. When a configuration file exists, you can use service management commands instead of command-line flags.
Run vemari init to create a configuration file, install vemari as a system service, and start it automatically. Use vemari init --force to stop, uninstall, overwrite config, and reinstall everything from scratch.
Run vemari config to open the configuration file in your default editor. If the file doesn't exist, it will be created automatically. Use vemari config --force to overwrite an existing configuration with defaults. Permission elevation is automatically requested if needed.
Place vemari.toml in the same directory as the vemari binary. The configuration file is automatically detected when running commands.
# Global proxy server address
proxy = "proxy.example.com:PORT"
# Self-healing configuration (enabled by default)
# [heal]
# enabled = false
# interval = 30
# failure_threshold = 3
# Services configuration
# Each service has a UUID (auto-generated), name, and required secret (auto-generated)
[[services]]
id = "550e8400-e29b-41d4-a716-446655440000"
name = "mydb"
type = "produce"
target = "localhost:5432"
secret = "auto-generated-strong-secret"
enabled = true
[[services]]
id = "550e8400-e29b-41d4-a716-446655440001"
name = "remotedb"
type = "consume"
local = 5433
secret = "same-secret-as-producer"
enabled = true| Field | Description | Required |
|---|---|---|
id | UUID for unique service identification (auto-generated if missing) | Auto-generated |
name | Human-readable service name | Yes |
type | Service type: "produce", "consume", or "expose" | Yes |
target | Local address (for produce/expose services) | For produce/expose (or use folder) |
folder | Folder path to share (for produce/expose services) | For produce/expose (alternative to target) |
local | Local port number (for consume services) | For consume |
secret | Required secret key for service access (auto-generated if missing) | Auto-generated |
enabled | Whether the service should start automatically | No (default: false) |
UUID-Based Identification
Services are identified by UUID to prevent naming conflicts. You can reference services by either UUID or name in commands. UUIDs and secrets are automatically generated when creating services.
Backward Compatibility
Command-line flags (-produce, -consume, -expose) continue to work as before. Configuration files are only used when not running with these flags.
When using a configuration file, Vemari provides commands to manage your services:
$ vemari init
$ vemari init --forceCreate config file, install vemari as a system service, and start it. If the service is already running, it will tell you. Use --force to stop, uninstall, overwrite config, and reinstall from scratch.
$ vemari config
$ vemari config --forceOpen configuration file for editing in your default editor. If the file doesn't exist, it will be created automatically. Use --force to overwrite with defaults. Permission elevation is automatically requested if needed.
$ vemari add
$ vemari add <token>Interactive service creation wizard, or add service from encrypted pairing token.
$ vemari token mydb
$ vemari token <uuid>Generate encrypted pairing token for an existing service (by name or UUID).
$ vemari listDisplay all configured services with UUIDs, names, and status.
$ vemari run
$ vemari run mydb
$ vemari run <uuid>Run all enabled services, or a specific service by name or UUID.
$ vemari install
$ vemari uninstall
$ vemari reinstall
$ vemari start
$ vemari stop
$ vemari restart
$ vemari statusInstall vemari as a system service for automatic startup on boot. Self-healing is enabled by default in service mode. Use reinstall to update the service after upgrading vemari.
Automatic Resume on Linux
On Linux, vemari install also creates a resume service that automatically restarts vemari when the system wakes from suspend/hibernate. This ensures your tunnels reconnect after laptop lid open or sleep.
$ vemari ping
$ vemari heal
$ vemari heal --onceMonitor service health and run self-healing watchdog. See the Self-Healing section for details.
Vemari includes a built-in self-healing watchdog that monitors the proxy server connection and automatically restarts the service when connectivity issues are detected and resolved. This ensures your tunnels stay connected even after network interruptions.
Enabled by Default
Self-healing is automatically enabled when running as a system service. You can customize or disable it via configuration.
Periodically checks if the vemari proxy server is reachable
Tracks consecutive connection failures
When server becomes unreachable for the configured threshold, marks as unhealthy
When server becomes reachable again, automatically restarts the vemari service to re-establish all tunnel connections
Add a [heal] section to your vemari.toml to customize self-healing behavior:
# Self-healing configuration (enabled by default)
# Monitors server connection and auto-restarts when needed
[heal]
enabled = false # Set to false to disable auto-healing
interval = 30 # Check interval in seconds (default: 30)
failure_threshold = 3 # Consecutive failures before triggering recovery (default: 3)You can also run the watchdog manually for monitoring and testing:
Continuous monitoring (runs until Ctrl+C):
vemari healCustom check interval (every 60 seconds):
vemari heal --interval=60Custom failure threshold (5 failures before unhealthy):
vemari heal --threshold=5Single health check (useful for cron/scripts):
vemari heal --once # exit code: 0=healthy, 1=unhealthyAutomatically recover from network interruptions without manual intervention
Ensure tunnels stay connected in production environments
Use `--once` mode for integration with monitoring systems
Monitor proxy server availability and connection health
The -produce flag exposes a local service to be accessible through the proxy server.
vemari [-proxy <server:port>] -produce <service-name> -target <local-address> [-secret <key>]| Flag | Description | Required | Example |
|---|---|---|---|
-proxy | Proxy server address | No | proxy.example.com:PORT |
-produce | Unique name for the service | Yes | mydb, webapp |
-target | Local address to expose (or use -folder) | Yes* | localhost:5432 |
-folder | Folder path to share (alternative to -target) | No | /home/user/documents |
-secret | Secret key for service access (auto-generated in config mode) | No* | my-secret-key |
UUID-Based Identification
Services are identified by UUID to prevent naming conflicts. Service names are for display purposes only.
STCP Protocol
Services are exposed using STCP (Secure TCP), which requires consumers to know the service UUID/name and secret key. No public ports are exposed.
The -consume flag creates a local listener that tunnels connections to a remote service.
vemari [-proxy <server:port>] -consume <service-name> -local <port> [-secret <key>]| Flag | Description | Required | Example |
|---|---|---|---|
-proxy | Proxy server address | No | proxy.example.com:PORT |
-consume | Name of service to connect to | Yes | mydb |
-local | Local port to listen on (1-65535) | Yes* | 15432 |
-folder | Path for folder service (creates WebDAV server) | No | /mnt/remote-files |
-secret | Secret key matching producer's secret (required, auto-generated in config mode) | No* | my-secret-key |
Local Port Binding
The service will be accessible on your local machine at the specified port. Make sure the port is not already in use by another service.
The -expose flag exposes a local HTTP service publicly with a custom subdomain at vemari.one. All services are automatically secured with HTTPS.
vemari [-proxy <server:port>] -expose [subdomain] -target <local-address>| Flag | Description | Required | Example |
|---|---|---|---|
-proxy | Proxy server address | No | proxy.example.com:PORT |
-expose | Subdomain name (optional, random name generated if not provided) | No | myapp, api, or omit for random name |
-target | Local HTTP service address (or use -folder) | Yes* | localhost:8080 |
-folder | Folder path to expose with file browser | No | /home/user/public |
Automatic HTTPS
All exposed services are automatically secured with TLS using Let's Encrypt wildcard certificates. Your service will be accessible at https://{subdomain}.vemari.one with valid SSL certificates.
Public Access
Your service will be accessible at https://{subdomain}.vemari.one. The subdomain must be unique across all exposed services.
Vemari includes an interactive service creation wizard that guides you through setting up any service type. Secrets are automatically generated, and for produce/expose services, you'll receive an encrypted pairing token.
vemari addPrompts for service type (produce, consume, or expose)
Asks for service name and type-specific configuration
Auto-generates a cryptographically secure secret key
For produce/expose services, outputs an encrypted pairing token
Auto-Generated Secrets
All services automatically get a strong, unique secret key. No need to manually create or share secrets when using the interactive wizard.
Vemari supports encrypted pairing tokens for easy service setup across different machines. Tokens contain all necessary configuration (UUID, name, secret, proxy address) encrypted with AES-GCM.
Generate a pairing token for any existing service (by name or UUID):
vemari token mydb
vemari token 550e8400-e29b-41d4-a716-446655440000The token contains the opposite service type. For example, a produce service generates a consume token.
On another machine, add the service from the token:
vemari add <encrypted-token>This automatically creates the matching service with all correct settings, including the secret key.
Tokens are encrypted with AES-GCM using a shared encryption key
Only clients with the shared key can decrypt tokens
Tokens include secrets, eliminating manual secret sharing
Token Workflow
1. Create a produce service with vemari add
2. Copy the generated token
3. On another machine, run vemari add <token>
4. The matching consume service is automatically created
All services require a secret key for security. Secrets are automatically generated when creating services interactively or via configuration file. Secrets are cryptographically secure 32-byte random values.
When creating services with vemari add, secrets are auto-generated
When saving configuration files, missing secrets are auto-generated
Secrets are included in pairing tokens for easy sharing
For command-line flag mode, you can manually specify secrets:
Producer side:
vemari -produce mydb -target localhost:5432 -secret my-secret-keyConsumer side (must match):
vemari -consume mydb -local 5432 -secret my-secret-keySecret Matching
The secret key must match exactly between producer and consumer. When using token-based pairing, secrets are automatically shared securely through encrypted tokens.
All communication between clients and the proxy server is encrypted end-to-end using AES-256-GCM.
Data is unreadable to eavesdroppers
Tampering is detected
Only authorized clients can connect
Vemari uses environment variables for configuration. The client ID defaults to "client".
| Variable | Description | Default |
|---|---|---|
VEMARI_AUTH_TOKEN | Authentication token for proxy server | Default encryption key |
Example:
export VEMARI_AUTH_TOKEN=my-auth-token
vemari -produce mydb -target localhost:5432Access a remote PostgreSQL database through Vemari:
On the database server:
vemari -produce postgres -target localhost:5432On your local machine:
vemari -consume postgres -local 5433Connect using psql:
psql -h localhost -p 5433 -U myuser -d mydbAccess a remote web application or API using STCP:
On the server running the web app:
vemari -produce webapp -target localhost:3000On your local machine:
vemari -consume webapp -local 8080Access the app:
curl http://localhost:8080Or expose your web service publicly (automatically secured with HTTPS):
Expose local HTTP service:
vemari -expose myapp -target localhost:3000Access publicly:
curl https://myapp.vemari.oneVemari supports sharing folders via STCP (produce/consume) or exposing them publicly via HTTP with a rich file browser interface.
Share a folder securely with remote clients using STCP:
On the server with the folder:
vemari -produce myfiles -folder /home/user/documents -secret my-secret-keyOn remote machine, access folder via WebDAV:
vemari -consume myfiles -folder . -secret my-secret-keyExpose a folder publicly with a beautiful web-based file browser:
Expose folder with custom subdomain:
vemari -expose myfiles -folder /home/user/public -secret optional-secretAccess publicly:
curl https://myfiles.vemari.one© 2025 DA Solutions. All Rights Reserved.