Desktop Application Guide

The ACT Desktop app wraps the powerful act-api in a convenient, native window using Tauri. However, it behaves slightly differently than a server-based installation.

The Sidecar Lifecycle

The Desktop app runs act-api as a Sidecar Process.

Start: When you open the App, it spawns act-api in the background.
Stop: When you quit the App (Cmd+Q / Right Click -> Quit), it sends a kill signal to the act-api process.

Note: Minimizing or closing the window does not stop the background process on some OS configurations (like macOS). It keeps running to ensure deployments finish. Exiting fully is required to stop the engine.

Data Location

The Desktop app stores its embedded database (act.db) and SSH keys in your OS’s standard application support directory:

macOS: ~/Library/Application Support/act-desktop/
Linux: ~/.config/act-desktop/
Windows: %APPDATA%\act-desktop\

If you need to back up your desktop data, this is the folder to zip.

The “Localhost Trap”

By default, the Desktop app configures the API to listen on 127.0.0.1 (localhost).

The Problem: External servers you provision cannot talk back to your laptop.

Setup callbacks (/api/v1/setup/callback) will fail.
Agent metrics (/api/v1/metrics) will fail.

The Solution: If you are managing remote VPS instances from your local Desktop app, you must expose your local API to the internet.

Cloudflare Tunnel (Recommended): Run cloudflared tunnel to expose port 8080.
Ngrok: Run ngrok http 8080.
Tailscale: Use Tailscale Funnel.

Once you have a public URL (e.g., https://my-act.ngrok.io), update the Public API URL in the Settings page so servers know where to send their data.