Desktop App Setup

Install the Portlama Desktop app for a native GUI experience with automatic service discovery and one-click tunnel creation.

In Plain English

The Portlama Desktop app is a native application (built with Tauri) that replaces the manual Chisel client setup. Instead of downloading plists, editing configuration files, and running terminal commands, you get a graphical interface that:

• Discovers local services automatically — it scans your machine for well-known services (Ollama, ComfyUI, PostgreSQL, Redis, Docker containers, etc.) and shows them in a marketplace-style UI
• Creates tunnels with one click — select a detected service, click "Expose," and the app creates the tunnel, updates the Chisel config, and reloads the connection
• Manages everything visually — start/stop Chisel, view logs, manage tunnels, rotate certificates, all from a native window with a system tray icon
• Provisions servers from the app — create a DigitalOcean droplet, install Portlama, and connect automatically without ever touching SSH
• Manages multiple servers — switch between servers, add existing servers manually, or remove servers from the registry

Prerequisites

• A completed Portlama onboarding on your VPS
• An agent certificate (.p12 file and password) — generated from the panel's Certificates page
• macOS (Apple Silicon or Intel) or Linux (x64)
• Node.js >= 20 (for the npx installer)

Do not use the admin certificate. Generate a scoped agent certificate from the panel. See Certificate Management.

Installation

Run the installer:

npx @lamalibre/install-portlama-desktop

The installer:

1. Detects your platform (macOS arm64/x64 or Linux x64)
2. Downloads the latest release from GitHub
3. Caches the download in ~/.portlama/desktop/
4. Installs the app:
   • macOS: Mounts the DMG, copies to /Applications, clears Gatekeeper quarantine, launches
   • Linux: Copies the AppImage to ~/.local/bin/portlama-desktop, makes it executable, launches

On subsequent runs, the installer uses the cached download if the version hasn't changed.

macOS Gatekeeper Note

The app is not code-signed with an Apple Developer certificate. On first launch:

• The installer attempts to clear the quarantine attribute automatically
• If macOS still blocks it: right-click the app → Open, or go to System Settings → Privacy & Security → Open Anyway

Initial Setup

After the app launches, it shows a setup screen with two options:

Option A: Connect to an existing server

Run the agent setup command:

npx @lamalibre/portlama-agent setup --label my-server

The --label flag names this agent connection (used for multi-agent support). This command connects to your VPS panel using the agent certificate and configures the local Chisel client. During setup, the client certificate and key are extracted from the P12 bundle for mTLS client authentication. Once setup completes, the app detects the configuration and switches to the main interface.

Option B: Create a new server

Click "Create a new server" on the setup screen. This opens the Servers tab where you can provision a DigitalOcean droplet directly from the app. See the Servers section below for details.

Using the App

The desktop app has two modes, toggled via a pill switch in the sidebar header. The mode toggle only appears when an admin certificate is detected for the active server.

Agent Mode (default)

Agent mode provides local agent management. The agent-mode pages (Dashboard, Tunnels, Services, Logs, Settings) are imported from the shared @lamalibre/portlama-agent-panel package. The landing page is the Agents list, showing all configured agents with their connection status. Click an agent to drill into its management pages:

• Agents (landing) — list of all configured agents with start/stop controls and status
• Dashboard — per-agent connection status, Chisel version, start/stop/restart controls
• Tunnels — per-agent tunnel list with FQDNs, ports, and status
• Services — marketplace-style service discovery with one-click expose
• Logs — per-agent Chisel client stdout and stderr logs
• Settings — per-agent certificate management, agent configuration

Server Mode

Server mode provides the full admin panel — the same management pages available in the browser-based panel UI. These pages are imported from the shared @lamalibre/portlama-admin-panel package:

• Dashboard — system stats (CPU, RAM, disk, uptime) + service health
• Tunnels — tunnel CRUD + Mac plist download
• Services — service control + live log viewer
• Static Sites — site CRUD + file browser + upload
• Users — Authelia user CRUD + TOTP enrollment
• Certificates — Let's Encrypt + mTLS cert listing + renewal + rotation
• Tickets — agent-to-agent authorization scope and session management
• Plugins — plugin management + push install UI
• Logs — live journald log streaming
• Settings — panel configuration, 2FA, admin auth mode

Admin certificate requirements: Cloud-provisioned servers automatically include an admin certificate, so Server mode is available immediately. For servers set up via portlama-agent setup, you need to manually import an admin certificate (P12 file) to unlock Server mode.

Dashboard

Shows connection status (connected/disconnected), Chisel version, and controls to start/stop/restart the tunnel client.

Tunnels

Lists all configured tunnels with their FQDNs, ports, and status. Create new tunnels or delete existing ones. Changes automatically reload the Chisel client.

Services

The marketplace-style service discovery page:

• Category filters: All, AI, Database, Docker, Dev, Media, Monitoring, Custom
• Automatic detection: Scans for 17 well-known services plus all Docker containers
• Status indicators: Running (green), Installed (amber), Not Found (gray)
• One-click expose: Click "Expose" on any running service to create a tunnel
• Custom services: Add your own service definitions with name, port, binary, process name, and category

Built-in services detected:

Service	Default Port	Category
Ollama	11434	AI
ComfyUI	8188	AI
LM Studio	1234	AI
Stable Diffusion WebUI	7860	AI
Open WebUI	3000	AI
LocalAI	8080	AI
Jupyter	8888	Dev
VS Code Server	8080	Dev
n8n	5678	Dev
Grafana	3000	Monitoring
Home Assistant	8123	Media
Plex	32400	Media
MinIO	9000	Database
PostgreSQL	5432	Database
Redis	6379	Database
MongoDB	27017	Database
Elasticsearch	9200	Database

Docker containers with exposed ports are also detected and can be individually exposed.

Servers

The multi-server management page:

• Cloud provisioning — create a DigitalOcean droplet with Portlama pre-installed. The wizard validates your API token scopes, measures latency to each region, provisions the droplet, installs Portlama, downloads the certificate, and connects the app automatically
• Add existing server — connect to a server you already set up manually by providing the panel URL and certificate
• Server switching — switch the active server; the app reloads configuration and reconnects
• Server removal — remove a server from the registry (cloud-provisioned servers can also be destroyed)

Cloud provider tokens are stored in your OS credential store (macOS Keychain or Linux libsecret) — never in plaintext files or process arguments. P12 passwords for each server are also stored in the credential store.

Server registry is persisted at ~/.portlama/servers.json. When this file exists and contains an active entry, it takes precedence over the legacy ~/.portlama/agent.json configuration.

Logs

View Chisel client stdout and stderr logs.

Settings

Certificate management — rotate or re-download the agent certificate, uninstall the agent.

Updating

Run the installer again to get the latest version:

npx @lamalibre/install-portlama-desktop

If a new release is available, it downloads and installs the update. The previous version is replaced.

Uninstalling

macOS:

rm -rf /Applications/Portlama.app
rm -rf ~/.portlama/desktop/

Linux:

rm ~/.local/bin/portlama-desktop
rm -rf ~/.portlama/desktop/

To also remove the agent configuration:

rm -rf ~/.portlama/

Quick Reference

Action	Command / Location
Install	npx @lamalibre/install-portlama-desktop
Update	npx @lamalibre/install-portlama-desktop
Agent setup	npx @lamalibre/portlama-agent setup --label <name>
App location	/Applications/Portlama.app (macOS)
Agent registry	~/.portlama/agents.json
Per-agent data	~/.portlama/agents/<label>/
Config (legacy)	~/.portlama/agent.json
Server registry	~/.portlama/servers.json
Service registry	~/.portlama/services.json
Download cache	~/.portlama/desktop/
Chisel logs	~/.portlama/agents/<label>/logs/chisel.log
Cloud tokens	OS credential store (com.portlama.cloud)
P12 passwords	OS credential store (com.portlama.server)
npm package	@lamalibre/install-portlama-desktop

Related Documentation

• Cloud Provisioning — step-by-step guide to creating a server from the desktop app
• Mac Client Setup — manual CLI-based Chisel setup (alternative)
• Certificate Management — generating agent certificates
• First Tunnel — creating tunnels via the panel UI
• Quick Start — full setup walkthrough