DOCUMENTATION

Deploy TucDesk in cloud or self-hosted mode

Operational documentation for installing agents, running the open source infrastructure, configuring the closed-source dashboard image, and understanding the encryption model.

GETTING STARTED

Cloud Quickstart

Sign up at app.tucdesk.app.
Install the agent on a machine.
Pair with the displayed key.
Open a browser, TUI, or mobile session.

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

What happens during first install

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 the pairing key. In staging, every hosted endpoint resolves to staging infrastructure: installer from https://get.tucdesk.app/install.sh, API from https://api.tucdesk.app, and rendezvous from https://rendezvous.tucdesk.app.

SELF-HOSTING

Self-Hosted Quickstart

Self-hosting requires a Linux host, public IP, DNS records for dashboard, API, rendezvous, and relay, Docker with Compose v2, a Postgres database, Redis, SMTP, object storage for recordings, and inbound UDP+TCP access to the relay port.

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

Public endpoint model

Internal service URLs can be Docker-network names such as http://api:8090. Public URLs must be internet reachable because agents and mobile apps use them from outside the Docker network.

TUCDESK_PUBLIC_API_URL=https://api.yourdomain.com
TUCDESK_PUBLIC_RENDEZVOUS_URL=https://rv.yourdomain.com
TUCDESK_PUBLIC_RELAY_ADDR=rv.yourdomain.com:4101
TUCDESK_DASHBOARD_URL=https://dash.yourdomain.com█

Agent profile persistence

Self-hosted install commands pass explicit environment variables. The installer writes those values to the agent config file so the service does not depend on shell environment variables after reboot.

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

ARCHITECTURE

How TucDesk works

API

REST and WebSocket control plane. Auth, teams, sessions, policy, recordings, and audit live here.

Rendezvous

Agent registration, discovery, and signaling. Agents prove identity with signed payloads.

TURN Relay

UDP/TCP relay fallback. It carries ciphertext only and cannot decrypt sessions.

Dashboard

Next.js web control plane. Self-hosters run the same image with TUCDESK_API_URL at runtime.

ServerProfile

Client boundary object that resolves cloud defaults, env overrides, or saved self-hosted endpoints.

Recordings

Tenant-prefixed object paths under recordings/{team_id}/{session_id}/ for isolation and deletion.

Mobile apps enter one dashboard URL, call /api/platform/profile, validate the returned profile, then save it in secure storage.

GET https://app.tucdesk.app/api/platform/profile

{
  "mode": "self_hosted",
  "api_url": "https://api.tucdesk.app",
  "rendezvous_url": "https://rendezvous.tucdesk.app",
  "relay_addr": "rendezvous.tucdesk.app:4102",
  "relay_url": "https://rendezvous.tucdesk.app"
}█

INSTALLATION

Agent and client installation

Surface	Install path	Notes
Linux Agent	curl shell installer, .deb, .rpm, .apk	amd64, arm64, and armhf rollout paths.
macOS Agent	shell installer, Homebrew, signed package	Apple Silicon and Intel supported.
Windows Agent	PowerShell, ZIP, MSI, setup EXE	Signed Windows packages for managed rollout.
iOS App	App Store / beta channel	First launch supports cloud or self-hosted dashboard URL.
Android App	Google Play / APK	Encrypted profile storage and biometric unlock.
TUI Client	Go release binary	Five-screen terminal client for operators.

AGENT RUNBOOKS

Install, operate, and recover every TucDesk surface

Each platform has the same operational shape: install, pair, verify connectivity, then keep a short recovery checklist close to the operator.

Linux Agent

Use the Linux agent for servers, containers hosts, and long-running fleet workers. It installs as a system service and keeps its TucDesk identity on disk.

Walkthrough

Install the signed agent artifact with the shell installer or package manager.
Pair the machine with a dashboard-generated key.
Tag the agent by role, region, and environment for fleet policy.
Verify that command execution and encrypted session consent match team policy.

Runbook checks

systemctl status tucdesk-agent
journalctl -u tucdesk-agent -n 200 --no-pager
tucdesk status

Wiki notes

Service: tucdesk-agent.service
Config: /etc/tucdesk/agent.env
Identity: /var/lib/tucdesk/identity.json

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

macOS Agent

Use the macOS agent for Apple Silicon and Intel workstations. The installer registers a launchd service and stores the agent profile locally.

Walkthrough

Run the installer from Terminal on the target Mac.
Approve the generated pairing key in the dashboard.
Grant any required local permissions for the workflows your team enables.
Confirm the launchd agent reconnects after logout or reboot.

Runbook checks

launchctl print gui/$UID/com.pth.tucdesk.agent
log show --predicate 'process == "tucdesk-agent"' --last 30m
tucdesk status

Wiki notes

Service: com.pth.tucdesk.agent
Config: /Library/Application Support/TucDesk/agent.env
Identity: /Library/Application Support/TucDesk/identity.json

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

Windows Agent

Use the Windows agent for managed desktop and server fleets. The service is designed for signed MSI rollout and policy-controlled pairing.

Walkthrough

Install with MSI, setup EXE, or PowerShell on the target host.
Pair with a dashboard key and assign environment tags.
Verify Windows service startup type and outbound access to rendezvous.
Test operator approval before enabling broad fleet commands.

Runbook checks

Get-Service TucDeskAgent
Get-EventLog -LogName Application -Source TucDeskAgent -Newest 50
tucdesk.exe status

Wiki notes

Service: TucDeskAgent
Config: C:\ProgramData\TucDesk\agent.env
Identity: C:\ProgramData\TucDesk\identity.json

irm https://get.tucdesk.app/install.ps1 | iex█

iOS App

Use the iOS app for approvals, fleet triage, recordings, and secure operator workflows from iPhone or iPad.

Walkthrough

Open the app and select cloud or self-hosted mode.
For self-hosted mode, enter the dashboard URL so the app can fetch its server profile.
Sign in, enable Face ID or Touch ID, and verify push notification delivery.
Approve a low-risk test session before using production agents.

Runbook checks

Check /api/platform/profile from the dashboard URL.
Confirm APNs permissions are enabled for TucDesk.
Use Settings to reset the saved server profile when moving environments.

Wiki notes

Storage: Keychain, WhenUnlockedThisDeviceOnly
Auth: Face ID / Touch ID
Discovery: dashboard profile endpoint and saved ServerProfile

Install TucDesk from the App Store, then choose TucDesk Cloud or enter your dashboard URL.█

Android App

Use the Android app for mobile fleet operations with biometric unlock, encrypted profile storage, and Google Play distribution.

Walkthrough

Open the app and select cloud or self-hosted mode.
Enter the dashboard URL for self-hosted deployments.
Sign in, enable Android biometrics, and confirm Firebase push delivery.
Open a test agent and review the consent prompt before production use.

Runbook checks

Check /api/platform/profile from the dashboard URL.
Confirm notification permissions and battery optimization settings.
Use Settings to reset encrypted profile storage when switching servers.

Wiki notes

Storage: EncryptedSharedPreferences
Auth: Android biometric framework
Discovery: dashboard profile endpoint and saved ServerProfile

Install TucDesk from Google Play, then choose TucDesk Cloud or enter your dashboard URL.█

TUI Client

Use the terminal UI for keyboard-first operators who need agent search, session review, fleet runs, and audit inspection from a shell.

Walkthrough

Install the CLI or download the release binary.
Authenticate with a team-scoped API token.
Use tags and saved filters to narrow fleet actions.
Review audit output after every command or session workflow.

Runbook checks

tucdesk login
tucdesk agents list --tag prod
tucdesk fleet run --tag canary --command "uptime"

Wiki notes

Screens: agents, sessions, recordings, fleet, settings
Auth: team API token or operator login
Transport: API and rendezvous endpoints from ServerProfile

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

ENVIRONMENT VARIABLES

Self-hosted configuration

Variable	Required	Description	Example
TUCDESK_API_URL	yes	Internal URL the dashboard container 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 and signaling	https://rv.yourdomain.com
TUCDESK_PUBLIC_RELAY_ADDR	yes	Relay host and port reachable from agents	rv.yourdomain.com:4101
TUCDESK_PUBLIC_RELAY_URL	no	HTTPS relay service URL when separate from rendezvous	https://rv.yourdomain.com
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
TUCDESK_AUDIT_KEY_SECRET	yes	Hex key used to sign and verify audit entries	openssl rand -hex 32
SMTP_HOST	yes	SMTP host for invites and password reset	smtp.yourdomain.com
SMTP_PORT	yes	SMTP port used by the API mailer	587
SMTP_USERNAME	yes	SMTP username for transactional mail	noreply@yourdomain.com
SMTP_PASSWORD	yes	SMTP password or provider app password	provider secret
TUCDESK_RECORDING_KEY	recommended	Key used for session recording encryption	openssl rand -base64 32
TUCDESK_SERVER_CERT_FINGERPRINT	optional	sha256 certificate pin exposed to clients and installers	sha256:<64 hex chars>

SECURITY

Encryption architecture

Identity

ED25519 agent identity, signed registration, and operator-signed control actions.

Session

X25519 ECDH, HKDF label tucdesk-session-v1, and AES-256-GCM encrypted payloads.

Audit

Immutable signed audit records with exportable actor, action, and session context.

RUNBOOKS

Operational runbooks for humans and AI agents

Runbooks are written as deterministic procedures so an on-call engineer, an AI assistant, or an automation job can follow the same recovery path.

Staging deploy failure

Check GitHub Environment secrets, rerun deploy-staging, inspect /home/ubuntu/tucdesk-staging logs, and verify health at api-stag.

curl -fsSL https://api.tucdesk.app/healthz█

Audit signing key recovery

Use docs/runbooks/staging-audit-signing-key-recovery.md before rotating TUCDESK_AUDIT_KEY_SECRET.

docker compose --project-name tucdesk-staging --env-file .env.staging logs api█

Agent cannot pair

Verify dashboard runtime config, rendezvous health, relay port 4101, and pairing key expiration.

curl -fsSL https://rendezvous.tucdesk.app/healthz█

Recording playback failure

Check recording path prefix, object storage credentials, encryption key, and presigned URL generation.

recordings/{team_id}/{session_id}/session.cast█

WIKIS + KNOWLEDGE GRAPH

How TucDesk documents itself for operators and AI

The documentation model is a graph: concepts link to config keys, runbooks, API endpoints, service ownership, risk controls, and verification commands.

TucDesk Knowledge Graph

ServerProfile
  ├─ Agent resolver: config file → env vars → cloud defaults
  ├─ Dashboard resolver: team runtime config → TUCDESK_API_URL → cloud defaults
  └─ Mobile resolver: Keychain/SecureStorage → first-run wizard

Runtime Config
  ├─ API: /v1/team/runtime-config
  ├─ Validate: /v1/team/runtime-config/validate
  ├─ Dashboard proxy: /api/team/runtime-config
  └─ Install command: generated from saved team config

Security Controls
  ├─ ED25519 identity
  ├─ X25519 session exchange
  ├─ AES-256-GCM transport
  ├─ ACL policy
  └─ Signed audit log█

MCP INTEGRATION

AI-agent safe fleet operations

MCP clients should use the same documented APIs and runbooks. Tools are scoped by API key permissions and all high-risk operations require policy evaluation and audit logging.

Tool group	Tools	Safety boundary
Inventory	list_agents, get_agent, get_security_posture	Read-only scopes and team_id isolation
Sessions	connect_session, list_sessions, get_recording	Consent gate, recording policy, audit entry
Execution	run_command, list_fleet_runs	ACL evaluation and human approval for high risk
Configuration	manage_acl, list_address_book, pair_agent	Admin scope and signed request proof

{
  "mcpServers": {
    "tucdesk": {
      "command": "npx",
      "args": ["-y", "tucdesk-mcp"],
      "env": {
        "TUCDESK_API_URL": "https://api.tucdesk.app",
        "TUCDESK_API_KEY": "tdk_..."
      }
    }
  }
}█

API REFERENCE

Authenticated API surface

Area	Purpose
Authentication	Operator login, refresh, invite, API key, and signed request verification.
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 Integration	AI-safe tools for fleet status, sessions, audit, ACL, and pairing.