Zorven documentation

Installation

The Zorven client is a single binary (zorven). The install scripts download it, write your token and server address to the system configuration, and start the background service.

Linux and macOS

The script installs to /usr/local/bin/zorven and needs root because it creates a system service. Get a token from the dashboard (see Quick start) and pass it as a flag:

If you omit the token, the script asks for it. To read the script before running it:

Windows

Open PowerShell as Administrator. The script installs under C:\Program Files\Zorven and starts the Windows service:

To inspect it first, save the output of irm https://zorven.app/install.ps1 to a file and read it.

Desktop app

A graphical installer for Windows: Zorven-Setup-windows-amd64.exe. See the Download page for details and other platforms.

Manual download

If you prefer not to use a script, download the binary directly, make it executable and put it in a directory on your PATH.

The current release is listed in /bin/manifest.json. The client can update itself; pass --no-auto-update to turn that off.

Quick start

1. Sign up and create a token Open the dashboard, create a client and copy its client token, which starts with zrv_live_. The token is a device identity, so keep it private.
2. Save the token
   $zorven authtoken zrv_live_...

   Copy
3. Publish a local port
   $zorven http 3000

   Copy
   The https://<name>--slug.zorven.app address in the output is live immediately with a valid TLS certificate. WebSocket, HTTP/2 and SSE work. The client prints a status box: Durum: Cevrimici (Online), Genel URL: https://<name>--slug.zorven.app, Yerel Hedef: http://localhost:3000 (the labels are printed in Turkish).
4. Need a throwaway tunnel?
   $zorven ephemeral 3000 --ttl 30m

   Copy
   The tunnel deletes itself when the time is up. At start it prints Gecici tunel: 30m0s sonra kendiliginden kaldirilacak. (that is, it will be removed automatically after the TTL).

CLI commands

These are the real commands of the client. Run zorven <command> --help for help on any of them.

zorven http <port> and zorven <port>

Exposes a local HTTP service to the internet. The short form zorven 8080 does the same thing.

Remote terminal and screen sharing are off by default in the CLI and in service mode; in the Windows desktop app they are on by default. To use them from the dashboard with the CLI, enable them explicitly on this device (0.2.2 and later):

Panel terminal: the client reports the shells installed on the machine, and you pick one when opening a new tab (bash, zsh, fish, sh, PowerShell 7, Windows PowerShell, cmd, WSL). You can open up to 8 tabs per client, with search, font size and copy-on-select. zsh and bash start with the Zorven profile (prompt, autosuggestions, syntax highlighting); use --terminal-plain-zsh / --terminal-plain-bash for a plain shell. The shell lives on the server: navigate away or reload and the tab reattaches to the same shell and replays recent output. After the connection drops the shell waits 30 minutes; closing the tab ends it. Only the person who opened a session can reattach to it.

zorven ephemeral <port>

Opens a temporary tunnel that deletes itself when its time is up, which suits demos, webhook testing and PR previews. --ttl must be between 1 minute and 24 hours (default 2h). Aliases: temp, tmp.

zorven authtoken <token>

Saves the client token to the local configuration. The token must start with zrv_live_, otherwise the command fails. Alias: token.

status, update, version

Shows the client version, the config file, server address, the saved token (masked) and the state of the background service (version line in 0.2.2 and later).

Downloads and applies a new release if there is one (the client restarts).

Prints the client and protocol versions plus the OS and architecture. Include this output in support requests.

zorven config

The --system flag writes the setting system-wide (for service mode) and needs administrator/root rights. See Configuration.

zorven connect Team+

Joins the Zorven Network and opens a local SOCKS5 proxy (default 127.0.0.1:1080). Your applications reach private resources that are never exposed to the internet (for example db.internal:5432) by name. This command needs an API token, not a client token (API Keys in the dashboard, at least the tunnels:read scope). The token must belong to a service account, and a resource policy granting that service account access must exist (REST API: POST /resource-policies, grant.service_account_ids); without a policy the connection cannot reach any resource.

Then use 127.0.0.1:1080 as the SOCKS5 proxy in your application. For example with SSH:

In gateway (site-to-site) mode you can expose the proxy to your LAN; allowed client ranges are mandatory in this mode:

zorven forward <host>

Binds a local port to an SNI-mode raw TCP tunnel (the visitor side). For example, to join a game server:

Then point your application at 127.0.0.1:25565. Use --listen to listen on a different address. This command supports TCP only; for UDP use the reserved-port mode in the dashboard.

Common flags

Available on zorven, zorven http and zorven ephemeral (0.2.2 and later; earlier versions only accept them on zorven [port]):

Service mode

In service mode the client runs in the background without a logged-in session and starts on boot (Windows Service or systemd). The install scripts already do this; to set it up by hand, with administrator/root rights:

The service reads the system configuration, not your user settings, so write the token and server with --system (or with service install --token). zorven authtoken alone does not configure the service; use sudo zorven service install --token zrv_live_....

Configuration

The client uses two config files: a per-user config.json (in the zorven folder of your user config directory) and a system-wide file for service mode (Linux/macOS: /etc/zorven/config.json, Windows: %ProgramData%\zorven\config.json). Run zorven config show to see the effective values.

Environment variables are supported too:

If no server is set, the default zorven.app:443 is used. If you run your own server, set its address with zorven config set-server.

Dashboard concepts

You manage everything at panel.zorven.app. Below are the main concepts and the plan each one is available from; see pricing for current limits.

Organizations and projects

Every account belongs to an organization. Group tunnels, clients and domains into projects so staging, production and customer environments stay separate. The project count depends on the plan (Free 2, Hobby 3, Pro 10, Team 50).

Tunnels

A client (device) opens one or more tunnels. Tunnel types: HTTP/HTTPS, raw TCP (databases, SSH), SNI-mode TCP and UDP (game servers). HTTP tunnels support path-based routing, traffic policies and the request inspector in the dashboard (view headers and bodies, replay with one click). You can protect a tunnel with a password (Basic Auth) or visitor sign-in with Google/GitHub. You can resend captured requests (replay) and compare two responses (replay diff). The request inspector does not record requests rejected early by authentication, policy or IP rules (401, policy, IP). Node and Python SDKs are available too.

Domains

Each tunnel gets a free tenant address (name--slug.zorven.app, where slug is your organization's short name) with automatic HTTPS. Under Domains in the dashboard you can also claim a global short name such as name.zorven.app (first come, first served): 1 on Pro, 3 on Team, 10 on Enterprise; Pro+. If your plan drops, short names and custom domains beyond the quota are not deleted but suspended (access closed); they reopen, oldest first, when you upgrade. Names containing zorven or rpshell cannot be taken. Add your own domain (for example api.yourcompany.com) in the dashboard and create the DNS records it shows (ownership verification and CNAME); Zorven then issues and renews the certificate automatically. Custom domains are available from Hobby+.

Certificates: the platform wildcard certificate for *.zorven.app is obtained outside the server through DNS validation (acme.sh) and loaded from a file; certificates for custom domains are issued automatically by Let's Encrypt (HTTP-01 and TLS-ALPN-01). The TLS handshake is refused for a custom domain whose DNS validation is not complete.

Team

Invite members to your organization by email. Roles are owner, admin and member. The team page is available on Pro+ plans and the member limit depends on the plan (Pro 3, Team 5). OIDC SSO and 2FA are supported for company sign-in.

Policy and Secret Vault

The policy engine Pro+ lets you define rules from the dashboard without code: rate limit, deny, redirect, header injection (set_header), required mTLS (require_mTLS), a WAF (waf) and webhook signature verification (verify_webhook). The WAF catches SQL injection, XSS, path traversal, command injection and scanner User-Agents with OWASP-lite rules, and you can add custom regex rules. It checks the path, query, User-Agent, Referer and Cookie (not the request body); a match gets a 403. verify_webhook verifies GitHub, Stripe, GitLab, Shopify and Slack signatures (5-minute tolerance, body up to 1 MB); an invalid signature is rejected with 401. The Secret Vault Pro+ stores your secrets encrypted; {{secret:name}} is only resolved in the secret_ref field of verify_webhook.

Request order: the free plan's first-visit interstitial runs before the policy engine, and the per-tunnel request limiter runs after the policies. Load balancing Team+: round robin, weighted, least connections and latency strategies, with HTTP and TCP health checks.

Plan gates

When you exceed a quota, connections are not cut; speed is throttled to Free 1, Hobby 5, Pro 10, Team 25, Enterprise 100 Mbps. Pro includes a 7-day free trial. Log retention is enforced per plan (Free 1, Hobby 3, Pro 7, Team 30, Enterprise 90 days; an hourly cleanup job); the audit log is kept for 365 days. On Team you can request extra devices ($0.50 per device per month) and extra traffic ($0.10 per GB) from Quotas and Plans in the dashboard; once approved, your limits rise.

Visitor login pages

When an HTTP tunnel has an access policy (Basic Auth or Google / GitHub), visitors see a Zorven-styled login page instead of the browser password popup. It supports Turkish and English, light and dark theme, and mobile.

• Username and password: the session lasts 12 hours. Changing the password invalidates existing sessions. Each IP can make at most 10 failed attempts per 10 minutes. curl and API clients can still pass with an Authorization: Basic header.
• Continue with Google / GitHub: only the providers the tunnel allows are shown; the allowed-email list applies and the visitor can switch account.
• Statistics: every attempt (method, provider, identity, success, reason, IP, user agent) is recorded; passwords never are. Records are kept for your plan's log retention. GET /api/v1/tunnels/{id}/access-events returns the list and GET /api/v1/tunnels/{id}/access-events/summary?window=24h|7d|30d a summary (analytics:read scope). A dashboard screen is coming later.

Web door (TCP/UDP) Pro+

For raw TCP/UDP tunnels (SNI included), the visitor signs in on the web and only their own IP address is allowed on the tunnel port. Connections without a grant are silently dropped.

1. Give the tunnel a sign-in method first: username and password, or Google / GitHub (access policy).
2. Enable the door and pick the grant duration: 3600 (1 hour), 43200 (12 hours), 86400 (24 hours) or 604800 (7 days).
3. Share the door URL with the visitor: door--<label>.zorven.app. After signing in, their IP can reach the port until the time is up; they can also close the door themselves.

Blocked attempts are counted in the access statistics. If the plan drops below Pro, the door closes automatically. No matching is done between IPv6 and IPv4 addresses.

Use in mail apps

You can use your platform mailbox (org-name@mail.zorven.app) in mail apps over IMAP and SMTP. In the dashboard's Mail section, use "Use in mail apps" to create an app password per mailbox; it is shown once and can be revoked any time.

• Gmail app (Android / iOS): add an account, choose "Other" or "Personal (IMAP)", and enter the settings above.
• Outlook and Thunderbird: autoconfig / autodiscover endpoints exist; entering the address may be enough.
• Apple Mail: download the configuration profile from the dashboard and install it.
• Sending to external recipients follows the same plan rule as webmail (Enterprise); internal platform addresses are always delivered.
• POP3 is not offered, only IMAP. The Gmail website adds external accounts over POP3, so you cannot add this account on gmail.com; use the Gmail app.

API and tokens

Everything you do in the dashboard is also available through the REST API. API access is available on Pro+ plans. Create an API token in the API Keys section of the dashboard, choosing its scopes and lifetime, and send it in the Authorization header:

Do not mix up the two token types: zrv_live_ is a client (device) token used with zorven authtoken; zrv_api_ is an API token used for the REST API and zorven connect. See the API reference for every endpoint and scope.

Help

See the FAQ for common questions, the status page for service health, and contact for anything else. The client and server are open core (AGPLv3): GitHub.