TucDesk

DOCUMENTATION

TucDeskDocumentation

Guides, references, and integration docs for the TucDesk platform.

QUICK START

Getting Started

TucDesk has three moving parts: the dashboard you operate from, the agent that runs on every machine you manage, and the rendezvous + relay layer that brokers encrypted connections between them. The fastest path is TucDesk Cloud — sign up, install an agent, and pair it.

curl -fsSL https://get.tucdesk.app/install.sh | bash█

The installer downloads the signed agent artifact, creates the service user, generates an ED25519 agent identity, writes the local config file, starts the system service, and prints a pairing key. Enter that key in the dashboard (or run tuc agent pair <key>) and the machine appears in your fleet within seconds.

No inbound ports are opened on managed machines. Agents dial out to https://rendezvous.tucdesk.app and sessions are end-to-end encrypted — the relay carries ciphertext only.

INSTALL

Installation

The same installer works on Linux and macOS; Windows uses PowerShell. Mobile clients install from the App Store and Google Play, and the TUI ships as a Go release binary alongside the agent.

# Linux / macOS
curl -fsSL https://get.tucdesk.app/install.sh | bash

# Windows (PowerShell)
irm https://get.tucdesk.app/install.ps1 | iex█

Surface	Install path	Notes
Linux Agent	shell installer, .deb, .rpm, .apk	amd64, arm64, armhf
macOS Agent	shell installer, Homebrew	Apple Silicon and Intel
Windows Agent	PowerShell, MSI, setup EXE	Signed packages for managed rollout
iOS App	App Store	Cloud or self-hosted dashboard URL
Android App	Google Play / APK	Encrypted profile storage
TUI Client	Go release binary	Keyboard-first operator client

CONFIGURE

Configuration

Agents read configuration from their local config file, falling back to environment variables, then cloud defaults. The dashboard and API are configured with environment variables; the most important ones for self-hosted deployments are listed below.

Variable	Required	Description	Example
TUCDESK_API_URL	yes	Internal URL the dashboard uses to reach the API	http://api:8090
TUCDESK_PUBLIC_API_URL	yes	Public API URL returned to clients	https://api.yourdomain.com
TUCDESK_PUBLIC_RENDEZVOUS_URL	yes	Public rendezvous URL for agent registration	https://rv.yourdomain.com
TUCDESK_PUBLIC_RELAY_ADDR	yes	Relay host:port reachable from agents — see self-hosting guide for port configuration.	rv.yourdomain.com:<port>
TUCDESK_DASHBOARD_URL	yes	Public dashboard URL used by mobile first-run discovery	https://dash.yourdomain.com
TUCDESK_POSTGRES_PASSWORD	yes	Postgres password for the self-hosted stack	generated secret
Audit signing key	yes	Secret key used to sign and verify the immutable audit chain. See the self-hosting setup guide for generation instructions.	see setup guide
Recording encryption key	recommended	Key for session recording encryption. See self-hosting guide.	see setup guide

CLI configuration lives in ~/.config/tuc/config.toml and is managed with tuc config set <key> <value>. See the command reference for the full list.

OPERATE

Agent Setup

Every platform follows the same operational shape: install, pair with a dashboard-generated key, tag the machine, then verify connectivity and policy. Agent identity is a locally generated ED25519 keypair tied to the machine — it never leaves the host.

# Pair, tag, and verify a new machine
tuc agent pair PK-4XQ9-71MZ
tuc agent tag agt_c31a0 prod
tuc agent info agt_c31a0█

On Linux the agent runs as tucdesk-agent.service with identity at /var/lib/tucdesk/identity.json; on macOS it registers a launchd service; on Windows it installs as the TucDeskAgent service. Use tucdesk status on any platform for a connectivity check.

OPERATE

Fleet Management

Tags are the targeting layer for everything: fleet runs, ACL policy, and operator search. A fleet run resolves a tag to a team-scoped agent set, evaluates policy, classifies risk, then dispatches in parallel with per-agent output and exit codes captured.

tuc fleet run --tag prod --command "systemctl restart nginx"
tuc fleet status
tuc audit export --from 2026-06-01█

MEDIUM-risk commands pause for confirmation and HIGH-risk commands require a single-use approval token bound to the exact command context. Every run writes one access decision per targeted agent to the immutable audit log.

TRUST

Security

Identity: agents register with locally generated ED25519 keys and sign every control payload. Operators authenticate to the API and sign sensitive actions; mobile clients add a biometric gate before high-risk approvals.

Sessions: each session performs an X25519 ECDH exchange, derives keys with HKDF (label tucdesk-session-v1), and encrypts payloads with AES-256-GCM. The relay forwards ciphertext only and cannot decrypt traffic.

Audit: every action — human or AI — produces a signed, tamper-evident audit entry with actor, action, target, risk tier, and approval state. Recordings are stored under tenant-prefixed object paths for isolation and clean deletion.

REFERENCE

API Reference

The authenticated REST and WebSocket API at https://api.tucdesk.app powers the dashboard, mobile apps, CLI, and MCP tools. All endpoints are team-scoped and audit-logged.

Area	Purpose
Authentication	Operator login, refresh, invites, API keys, signed requests.
Agents	List, pair, label, tag, and inspect online machines.
Sessions	Open, end, audit, record, and replay remote sessions.
Fleet	Run approved commands across tagged machines and inspect history.
Webhooks	Team-scoped event delivery for external systems.
MCP	AI-safe tools for fleet status, sessions, audit, ACL, and pairing.

# Health check
curl -fsSL https://api.tucdesk.app/healthz

# Mobile first-run discovery
GET https://tucdesk.app/api/platform/profile█

DEPLOY

Self-Hosting

Self-hosting requires a Linux host, public DNS records for the dashboard, API, rendezvous, and relay, Docker with Compose v2, Postgres, Redis, SMTP, object storage for recordings, and inbound UDP+TCP access to the relay port (configurable in your .env.selfhosted file — see setup guide).

cp .env.selfhosted.example .env.selfhosted
docker compose -f docker-compose.selfhosted.yml \
  --env-file .env.selfhosted up -d█

Agents installed against a self-hosted stack take their endpoints as explicit environment variables; the installer writes them to the agent config file so the service survives reboots without shell environment dependencies.

TUCDESK_MODE=self_hosted \
TUCDESK_API_URL="https://api.yourdomain.com" \
TUCDESK_RENDEZVOUS_URL="https://rv.yourdomain.com" \
TUCDESK_RELAY_ADDR="rv.yourdomain.com:<port>" \
TUCDESK_RELAY_URL="https://rv.yourdomain.com" \
curl -fsSL https://get.tucdesk.app/install.sh | bash█

Mobile apps connect to self-hosted deployments by entering one dashboard URL. The app calls /api/platform/profile, validates the returned profile, and saves it in secure storage.

START IN MINUTES

From zero to connected in under 2 minutes.

One install command. Automatic ED25519 identity. No firewall changes required. Free for up to 3 agents — no credit card needed.

Get Started Free Talk to Us