Desktop App

Agentcy ships a native macOS desktop app built with Tauri v2. It bundles the frontend, backend, and a setup wizard into a single application — no terminal required.

Installation

Request a build

Agentcy is closed-source. Request a signed Desktop .dmg via agentcylabs.com; we'll send a download link by email.

Install

1. Open the downloaded .dmg file
2. Drag Agentcy to your Applications folder
3. Launch Agentcy from Applications

macOS Gatekeeper

On first launch, macOS may show a warning about an unidentified developer. Right-click the app, select Open, and confirm. This is only required once.

Setup Wizard

On first launch, Agentcy opens a setup wizard that guides you through configuration. The wizard is a React app rendered in a WKWebView, separate from the main application UI.

Step 1: Choose a Setup Mode

Mode	Description	Requirements
Quick Setup	Automatically pulls and starts Docker containers for PostgreSQL, Neo4j, and Redis	Docker Desktop installed
Custom Local	Connect to your own database instances running on your machine or network	Existing PostgreSQL, Neo4j, and Redis
Cloud Deploy	Connect to a remote Agentcy deployment	A running Agentcy instance

Step 2: Infrastructure (Quick Setup)

If you chose Quick Setup, the wizard:

1. Checks that Docker Desktop is installed and running
2. Pulls the required images (postgres:16-alpine, neo4j:5-community, redis:7-alpine)
3. Creates and starts containers using desktop/docker-compose.desktop.yml
4. Waits for all services to become healthy
5. Displays connection details

The desktop Docker Compose file uses the same port mappings as the development setup:

Service	Port
PostgreSQL	15432
Neo4j (Bolt)	17687
Redis	16379

Step 2: Infrastructure (Custom Local)

If you chose Custom Local, provide connection details for each service:

PostgreSQL URL: postgres://user:pass@localhost:5432/agentcy
Neo4j URI:      bolt://localhost:7687
Neo4j User:     neo4j
Neo4j Password: your-password
Redis URL:      redis://localhost:6379

The wizard validates each connection before proceeding.

Step 2: Infrastructure (Cloud Deploy)

Connect to a remote Agentcy instance by providing:

Field	Example
API URL	https://agentcy.example.com
Auth method	Local credentials or OIDC

Supported cloud targets:

• Railway — deployed via Railway template
• Fly.io — deployed via fly launch
• AWS (ECS or EKS) — deployed via CloudFormation or Helm
• Kubernetes — any cluster with the Helm chart
• Docker Remote — any host running docker compose up

Step 3: LLM Provider

Configure which AI model powers the chat:

Provider	Configuration
Anthropic	API key (sk-ant-...)
OpenAI	API key (sk-...)
Ollama	URL (default: http://localhost:11434) — no API key needed
Custom	Any OpenAI-compatible endpoint URL + optional API key

Step 4: Authentication

Choose your auth mode:

• Local — built-in username/password authentication with bcrypt + JWT. A default admin account is created automatically.
• OIDC — connect to Auth0, Supabase Auth, Keycloak, or any OIDC provider. Provide JWKS URL, audience, and issuer.

Step 5: First Connector (Optional)

Optionally connect your first data source right from the wizard. The most common choice is a GitHub Personal Access Token.

Step 6: Complete

The wizard saves your configuration, starts the backend sidecar process, and opens the main Agentcy UI.

---

Architecture

The desktop app consists of three components:

Tauri Shell

The Tauri v2 Rust application (desktop/src-tauri/) manages:

• Window management — WKWebView for both the wizard and main app
• Sidecar lifecycle — starts and stops the agentcy-api backend binary
• Docker management — controls infrastructure containers via the Docker CLI
• System tray — menu bar icon for quick access and status
• Auto-updates — checks GitHub Releases for new versions via tauri-plugin-updater

Backend Sidecar

The backend is a compiled agentcy-api binary that runs as a child process of the Tauri app. It is the same Rust backend used in server deployments, just packaged as a sidecar.

The sidecar:

• Starts automatically when the app launches
• Reads configuration from the saved config file
• Runs database migrations on startup
• Listens on localhost:18080
• Is restarted automatically if it crashes

Frontend

The frontend is a static export of the Next.js application (output: 'export' in next.config.desktop.ts). It is embedded in the Tauri app bundle and served locally — no Node.js server is needed at runtime.

Static Export Considerations

Dynamic routes (e.g., /chat/[conversationId]) are split into a server-side page.tsx wrapper and a client-page.tsx client component. The static export uses generateStaticParams with a placeholder parameter to satisfy Next.js build requirements.

---

Configuration

All desktop app configuration is stored in a single JSON file:

~/Library/Application Support/com.agentcy.desktop/config.json

Example configuration:

{
  "setup_mode": "quick",
  "infrastructure": {
    "postgres_url": "postgres://postgres:password@localhost:15432/kgp",
    "neo4j_uri": "bolt://localhost:17687",
    "neo4j_user": "neo4j",
    "neo4j_password": "password",
    "redis_url": "redis://localhost:16379"
  },
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "api_key": "sk-ant-..."
  },
  "auth": {
    "provider": "local",
    "jwt_secret": "generated-random-string"
  },
  "server": {
    "bind_addr": "127.0.0.1:18080"
  }
}

Sensitive Data

The config file contains API keys and database passwords in plain text. It is readable only by the current user (file permissions 600), but be aware of this if you back up your home directory.

---

Logs

Application logs are written to:

~/Library/Logs/Agentcy/

This directory contains:

File	Content
agentcy.log	Main Tauri application log
backend.log	Backend sidecar (agentcy-api) output
docker.log	Docker container management operations

To stream backend logs in real time:

tail -f ~/Library/Logs/Agentcy/backend.log

---

Updating

The desktop app checks for updates on launch using the GitHub Releases endpoint. When an update is available:

1. A notification appears in the app
2. Click Update to download the new version
3. The app restarts with the updated version

You can also manually download the latest DMG from the Releases page.

---

Building from Source

To build the desktop app from source:

Prerequisites

• Rust toolchain (1.75+)
• Node.js 20+
• Xcode Command Line Tools (for macOS builds)
• Docker Desktop (for running infrastructure during development)

Development Mode

make desktop-dev

This starts the Tauri development server with hot reloading for both the Rust backend and the frontend.

Production Build

make desktop-build

This runs desktop/scripts/build-desktop.sh, which:

1. Builds the agentcy-api sidecar binary (release mode)
2. Builds the wizard React app
3. Exports the Next.js frontend as static files
4. Runs cargo tauri build to produce the .dmg

The output DMG is placed in desktop/src-tauri/target/release/bundle/dmg/.

Build Individual Components

# Build only the sidecar binary
make desktop-sidecar

# Run only the wizard in dev mode (Vite)
make desktop-wizard

---

Troubleshooting

App shows a blank white screen

The backend sidecar may have failed to start. Check ~/Library/Logs/Agentcy/backend.log for errors. Common causes:

• Docker Desktop is not running (Quick Setup mode)
• Database ports are already in use
• Invalid configuration in config.json

Docker containers fail to start

Ensure Docker Desktop is running and has sufficient resources allocated (at least 4 GB RAM recommended for Neo4j).

Cannot connect to backend

The sidecar listens on 127.0.0.1:18080. If another process is using this port, change server.bind_addr in config.json.

Resetting the app

To start fresh, delete the config file and relaunch:

rm ~/Library/Application\ Support/com.agentcy.desktop/config.json

The setup wizard will run again on next launch.

---

Next Steps

• Configuration — all environment variables and options
• Authentication — configure OIDC for team use
• Connectors Overview — connect your data sources