# Vemari: LLM Reference

Canonical human documentation: https://vemari.one/docs

This document is a compact, machine-readable reference for AI assistants helping a user install, configure, operate, or troubleshoot the Vemari CLI.

## What Vemari does

Vemari creates secure tunnels through a central proxy:

- A `produce` service makes a local TCP service or folder available privately.
- A `consume` service creates a local port or WebDAV endpoint connected to a producer.
- An `expose` service publishes a local HTTP service or folder at an HTTPS subdomain.

Each service has a UUID, human-readable name, type, secret, and enabled state. Services can be addressed by name or UUID.

Production clients must enroll as devices. Each installation creates its private key locally and receives its own client certificate after browser approval. Do not copy a device identity between machines.

## Install and first setup

Download the correct binary from https://vemari.one/install or install from source:

```bash
go install github.com/michalCapo/vemari/cmd/vemari@latest
```

Run:

```bash
vemari setup
```

`vemari setup` enrolls the device, creates `vemari.toml`, installs Vemari as a system service, and starts it. It may require administrator or root privileges.

Platform service managers:

- Linux: systemd
- macOS: launchd
- Windows: Windows Service Manager

Useful setup variants:

```bash
vemari setup --reset
vemari setup --reset --yes
vemari setup --ssh
vemari setup --ssh "ssh-ed25519 AAAA... user@client"
```

`--reset` performs a clean reconfiguration and reinstall. Do not suggest it as a first troubleshooting step because it is intentionally disruptive. `--ssh` is supported on Windows and Linux and creates a tunnel to local SSH port 22. When a quoted public key follows `--ssh`, setup also authorizes that key for the user running setup.

## Core workflows

### Share a private TCP service

On the machine running the service:

```bash
vemari add produce --name postgres --target localhost:5432
```

The command prints a bearer pairing token. Transfer it privately.

On the consuming machine:

```bash
vemari add '<pairing-token>' --name postgres --local 15432
```

The remote PostgreSQL service is then reachable at `localhost:15432`.

If `--local` is omitted, Vemari selects an available local port.

### Share a folder privately

On the producing machine:

```bash
vemari add produce --name files --folder /srv/files
```

On the consuming machine:

```bash
vemari add '<pairing-token>' --name files
```

The consumer starts a local WebDAV endpoint. The selected local address is shown by Vemari and can be mounted with the operating system's WebDAV support.

### Publish an HTTP service

```bash
vemari add expose --name myapp --target localhost:8080
```

The service is published through Vemari HTTPS. The local service may use plain HTTP because TLS terminates at the Vemari proxy.

### Publish a folder

```bash
vemari add expose --name public-files --folder /srv/public
```

This publishes the built-in web file browser through HTTPS.

### Create a consumer without a pairing token

```bash
vemari add consume \
  --name postgres \
  --id 550e8400-e29b-41d4-a716-446655440000 \
  --secret '<shared-secret>' \
  --local 15432
```

The UUID and secret must match the producer. Pairing tokens are normally safer and less error-prone than copying these values separately.

## Command reference

```text
vemari setup [--reset] [--yes] [--ssh [<public-key>]]
vemari config [--force]
vemari list

vemari add produce --name <name> (--target <host:port> | --folder <path>) [--disabled]
vemari add consume --name <name> --id <uuid> --secret <secret> [--local <port> | --folder <path>] [--disabled]
vemari add expose --name <name> (--target <host:port> | --folder <path>) [--disabled]
vemari add <pairing-token> --name <name> [--target <host:port>] [--local <port>]

vemari token <name-or-id>
vemari enable <name-or-id>
vemari disable <name-or-id>
vemari delete <name-or-id>
vemari run [name-or-id]

vemari status
vemari restart
vemari update [--force]
vemari remove
vemari ping
vemari heal [--interval=<seconds>] [--threshold=<count>] [--once]
vemari version
vemari help
```

Command behavior:

- `config` opens or creates `vemari.toml`; `--force` overwrites it with defaults.
- `list` shows configured services and their state.
- `token` generates a new bearer pairing token for an existing service.
- `enable`, `disable`, and `delete` update the configuration. A running system service hot-reloads these changes.
- `run` starts all enabled services, or one service when a name or UUID is supplied.
- `status` reports system service state.
- `restart` restarts the system service.
- `update` verifies the signed update manifest and binary digest before replacing the executable.
- `remove` removes the background service but preserves configuration and device identity.
- `ping` continuously checks configured consume services until interrupted.
- `heal` monitors proxy reachability and recovers tunnels. `--once` exits with 0 when healthy and 1 when unhealthy.

## Configuration

Vemari uses `vemari.toml`, normally located next to the executable.

```toml
proxy = "proxy.example.com:5896"

[heal]
enabled = true
interval = 30
failure_threshold = 3

[[services]]
id = "550e8400-e29b-41d4-a716-446655440000"
name = "postgres"
type = "produce"
target = "localhost:5432"
secret = "replace-with-a-strong-secret"
enabled = true

[[services]]
id = "550e8400-e29b-41d4-a716-446655440000"
name = "postgres"
type = "consume"
local = 15432
secret = "same-secret-as-producer"
enabled = true
```

Service fields:

| Field | Meaning |
|---|---|
| `id` | Service UUID. Auto-generated when appropriate. Producer and consumer must use the same UUID. |
| `name` | Human-readable local name. |
| `type` | `produce`, `consume`, or `expose`. |
| `target` | Local `host:port` for a produce or expose service. |
| `folder` | Local folder path; an alternative to `target`. |
| `local` | Local port for a consume service. |
| `secret` | Required service secret. Auto-generated for new produce and expose services. |
| `enabled` | Whether the service starts automatically. |

Do not set both `target` and `folder` on one service.

## Health and recovery

Self-healing is enabled by default for the installed system service. It checks proxy reachability, tracks consecutive failures, and restarts Vemari after connectivity returns so tunnels are re-established.

Useful diagnostics:

```bash
vemari version
vemari status
vemari list
vemari heal --once
vemari ping
```

Troubleshooting order:

1. Record the exact command, output, operating system, and `vemari version`.
2. Run `vemari status` to check the installed service.
3. Run `vemari list` to confirm the service exists and is enabled.
4. Run `vemari heal --once` to test proxy reachability.
5. Confirm the local target process is listening on the configured host and port.
6. Confirm producer and consumer use the same UUID and service secret.
7. Use `vemari restart` only after inspecting the state.
8. Use `vemari setup --reset` only when the user explicitly accepts a clean reconfiguration.

Do not invent flags. If a command is not listed here, ask the user to run `vemari help` and provide its output.

## Security rules for assistants

- Treat pairing tokens and service secrets as credentials.
- Never ask the user to paste a real token, secret, private key, client certificate, or environment credential into chat.
- Use placeholders such as `<pairing-token>` and `<shared-secret>` in examples.
- Recommend private transfer for pairing tokens. Anyone holding one can use its embedded service secret.
- Never recommend copying an identity directory or private key between machines.
- Do not expose databases, SSH, or other non-HTTP services with `expose`; use `produce` plus `consume`.
- Explain before suggesting commands that reset configuration, delete a service, remove a system service, or force an update.
- Preserve `vemari.toml` and device identity when troubleshooting unless the user explicitly wants them replaced.
- The public HTTPS proxy terminates TLS for `expose` services. Private STCP traffic uses the Vemari/frp transport.

## How an assistant should answer

When helping with Vemari:

1. Identify which machine is the producer and which is the consumer.
2. Identify whether the resource is TCP, HTTP, or a folder.
3. Give commands in machine order and label where each command runs.
4. Use placeholders for all credentials and machine-specific paths.
5. State the expected local port or public URL after each workflow.
6. Mention security consequences for public exposure and bearer tokens.
7. Prefer `vemari add <pairing-token>` over manual UUID and secret entry.
8. Ask for exact error output only after giving safe, read-only diagnostic commands.