Celistra Setup Guide: From Download to First Agent in 5 Minutes

This is the canonical setup guide. You'll download the Celistra daemon, pair your machine, spawn an agent, attach to it from your phone, and grant it a sandbox capability. Five minutes if you don't get distracted.

Prerequisites

• A Mac, Linux box, or Windows machine
• A Google account (for Firebase Auth)
• A browser

Step 1 — Install the daemon (1 minute)

macOS

Download from celistra.dev/download. Drag Celistra.app into /Applications. Double-click once to launch. The Celistra mark appears in your menu bar.

On first launch, the onboarding wizard opens. Three steps: welcome, workspace folder (default ~/CelistraAgents), permissions (skip what you don't need). Done.

Linux

curl -L https://celistra.dev/dl/celistrad-linux-amd64.tar.gz | tar xz
sudo mv celistrad /usr/local/bin/
celistrad install-systemd-unit
sudo systemctl enable --now celistrad

Windows

Download the signed MSI from celistra.dev/download. Run the installer. Celistra registers as a Login Item and appears in your system tray.

Step 2 — Pair the machine (30 seconds)

Open the dashboard at celistra.dev. Sign in with Google. The dashboard loads in the empty fleet-view state.

On the machine: click the Celistra tray icon → Pair this machine. The browser jumps to celistra.dev/pair?token=…. Constant-time compared, single-use, 600-second TTL. The handshake completes silently. The machine appears in your fleet view.

Step 3 — Spawn your first agent (1 minute)

From the dashboard, click Spawn agent. Pick the host. Enter the command — anything you'd run in a terminal:

claude --resume my-first-task

or

python3 my-script.py

Toggle Auto-restart if you want the daemon to respawn on crash (5/60s ceiling).

Hit Run. The PTY opens in your browser via xterm.js + WebSocket. The agent is now supervised by the daemon — survives terminal close, lid close, network drop.

Step 4 — Watch from your phone (2 minutes)

Install Celistra mobile (iOS via TestFlight: celistra.dev/mobile · Android via Play Store). Sign in with the same Google account. Your fleet view appears.

Tap the running agent. The PTY attaches; you can read along. When the agent asks for a permission ("can I run git push?"), the phone buzzes. Long-press → Approve. Face ID confirms. The agent continues.

Step 5 — Sandbox a capability (1 minute)

By default, agents can write inside the workspace and read everywhere — workspace_rw + read_anywhere + network + subprocess. If a particular agent needs more (e.g. screen recording for visual UI work), grant per-agent:

Tray menu → Edit Agent Capabilities… opens ~/.celistra_capabilities.json:

{
  "grants": [
    {
      "match": { "agentNamePattern": "screenshot-*" },
      "capabilities": ["screen_capture"]
    }
  ]
}

Save. Next spawn whose name matches gets the extra capability. The audit log records every grant.

Step 6 — When you're off Wi-Fi (0 minutes — automatic)

The dashboard probes 127.0.0.1:33120 first. If unreachable (you're at a coffee shop, the daemon is on your home laptop), it falls back to <machine>.tunnel.ujex.dev transparently. nginx terminates TLS with Let's Encrypt; CAA pinned. The user-visible difference: latency. Otherwise identical.

What you can do next

• Pair more machines (free covers 1; Pro $2/mo covers 5)
• Use celistrad ctl — readline REPL with tab completion + --json one-shot mode
• Wire git worktrees for parallel agents
• Pair with Ujex Postbox to give your agent a real email

Common first-time stumbles

Pricing

Free tier is real. Download.