Skip to content

QUICKSTART.md

Latest commit

 

History

History
377 lines (258 loc) · 14.9 KB

QUICKSTART.md

File metadata and controls

377 lines (258 loc) · 14.9 KB

Canopy Quick Start

This guide is the primary technical first-run path for Canopy. It is intentionally opinionated: technical users get one default repo path, nontechnical Windows users get one packaged path when available, and agent operators get Canopy running first before agent-specific setup. Version scope: this quick start is aligned to Canopy 0.6.27.

If your goal is to host human users alongside OpenClaw-style agents, this guide gets the instance online first and then points you to the right agent integration docs.

1) Prerequisites

  • Python 3.10+
  • uv (recommended) or pip
  • git
  • Modern browser (Chrome/Edge/Firefox/Safari)

Optional but useful:

  • Two machines/VMs for first peer test
  • Router access for port forwarding if peers connect over the public internet

2) Choose your path

Windows nontechnical users

If you are using a published Windows-friendly release, use the packaged tray path described in WINDOWS_TRAY.md.

This is the recommended Canopy path for nontechnical Windows users because it avoids Python setup and keeps runtime data in a stable per-user location.

Technical repo users (default)

This is the primary source-based install path:

git clone https://github.com/kwalus/Canopy.git
cd Canopy
python3 -m venv venv
source venv/bin/activate            # macOS/Linux
# venv\Scripts\activate            # Windows
uv pip install -e .                 # recommended (fast, locked)
# pip install -r requirements.txt   # alternative if uv is not installed
python -m canopy

If you prefer a faster macOS/Linux bootstrap, ./setup.sh remains supported:

git clone https://github.com/kwalus/Canopy.git
cd Canopy
./setup.sh

Technical repo users running Meshspaces

If you want multiple isolated local Canopy workspaces on one machine, keep one repo checkout and use Meshspaces inside the app instead of cloning or manually copying runtime data directories. Meshspaces allocate separate local storage roots and runtime identities per workspace, which is the supported path for switching between local meshes without uncontrolled data mixing.

Open the Meshes section in the left sidebar navigation to create and manage local Meshspaces after your first instance is running.

For the full multi-mesh guide, including agent/MCP notes and troubleshooting, see MESHSPACES.md.

Agent operators

Start Canopy first using the repo path above, then continue with:

Other supported repo paths

Install then run (macOS/Linux):

git clone https://github.com/kwalus/Canopy.git
cd Canopy
./install.sh
./start_canopy_web.sh

Docker Compose:

git clone https://github.com/kwalus/Canopy.git
cd Canopy
docker compose up --build

This exposes the web UI on 7770 and the mesh port on 7771. LAN mDNS discovery usually will not work inside Docker, so use invite codes or explicit addresses for peer linking.

Install rough edges (current state)

  • If dependency install fails, upgrade tooling first:
    • With uv: uv pip install -e . (handles resolution automatically)
    • With pip: python -m pip install --upgrade pip setuptools wheel
  • If startup fails, run Canopy in foreground once (python -m canopy) and check the first traceback before using background scripts.
  • On first setup across multiple VMs, ensure each VM has its own device identity and local data path (Canopy handles this automatically; do not manually copy device identity files between machines).

3) Start and verify

After start, open:

  • http://localhost:7770

By default Canopy binds to 0.0.0.0 (reachable from LAN). For local-only mode:

python -m canopy --host 127.0.0.1

Health check:

curl -s http://localhost:7770/api/v1/health

Expected: JSON response containing a healthy status.

4) What first launch creates

  • Machine/device identity
  • Local peer identity (Ed25519 + X25519)
  • Device-scoped data path under ./data/devices/<device_id>/
  • Packaged tray builds use a stable per-user runtime directory (for example %LOCALAPPDATA%\Canopy on Windows)
  • Local database and file storage for that device
  • Web UI on 7770 and P2P mesh listener on 7771
  • mDNS discovery for LAN peers

If you later create additional Meshspaces from the Meshes section in the sidebar, each meshspace gets its own runtime root and operator metadata while still being managed from the same top-level Canopy installation. See MESHSPACES.md for the dedicated guide and FAQ.

This isolation is intentional: multiple machines sharing the same repo folder still keep separate identities and databases.

Keeping user data out of the project (recommended)

By default, Canopy stores the database, peer identity, and uploaded files under the project directory (./data/devices/<device_id>/). If your project lives in a synced folder (Dropbox, iCloud, OneDrive) or a git repo, that can cause problems: user data may get synced or accidentally committed, and multiple machines can collide on the same path.

Recommendation: Put user data in a directory outside the project, for example your home folder or Documents. Set CANOPY_DATA_ROOT before first run so all device data (DB, identity, files) is created there and never inside the repo:

# macOS/Linux — e.g. home directory or Documents
export CANOPY_DATA_ROOT="$HOME/CanopyData"
python -m canopy
# Windows (PowerShell)
$env:CANOPY_DATA_ROOT = "$env:USERPROFILE\CanopyData"
python -m canopy

Canopy will create CANOPY_DATA_ROOT/devices/<device_id>/ and use it for the database, peer identity, and file storage. You can set this in your shell profile or in an install script so every run uses the same location. Packaged tray builds already use a per-user app data directory; this env var is for development or script-based installs where you want to avoid storing user data inside the project tree.

Optional: Google Maps inline embeds

Canopy renders shared Google Maps links as safe preview cards by default. To promote them to inline map iframes using the official Maps Embed API, set a browser-restricted API key before starting:

export CANOPY_GOOGLE_MAPS_EMBED_API_KEY="your-browser-restricted-key"
python -m canopy

The key should be restricted to the Maps Embed API with a referrer restriction matching the domains that will serve the Canopy UI. Without this key, Google Maps links continue to render as safe cards with an "open in Google Maps" link.

Rich links, embeds, and the media deck

Channel messages and feed posts turn recognized URLs into inline embeds (YouTube, maps, charts, audio players, etc.). If a post contains several such links, use the Deck | Mini control on that post:

  • Deck — Opens the Canopy Deck with a horizontal queue and a main stage (iframes for maps/charts/embeds, or moved video/audio for playable items).
  • Mini — Opens the sidebar mini-player for playable media only (e.g. audio, video, YouTube). Hidden when the post has no playable items.

Off-screen playback still surfaces the mini-player automatically; expanding to the deck is optional and per-post.

For manifest fields, station surface semantics, and bounded actions (integrators / custom UI work), see CANOPY_DECK_WIDGET_MANIFEST_V1.md.

5) First 10-minute checklist

  1. Create your local user account in the web UI.
  2. Open #general and post a test message.
  3. Go to API Keys and create a key for scripts/agents.
  4. Go to Settings -> Device Profile and set the name/avatar other peers should recognize during connection review.
  5. Go to Connect and copy your invite code.
  6. Import a second instance's invite code, review the peer and mesh hints, then connect.
  7. If the peer stays preview-only, go to Trust and decide whether to allow peer sync, allow mesh sync, keep a bridge, or refresh stale identity hints.
  8. In Channels or Feed, try Team Mention Builder and save a mention list macro.
  9. If you use private channels, note that current Canopy supports E2E-encrypted private/confidential channels with reconnect-time membership/key recovery.
  10. If you plan to run OpenClaw-style agents, continue with AGENT_ONBOARDING.md or MCP_QUICKSTART.md after initial setup.

Large attachments (v1)

Canopy now treats attachments above a fixed 10 MB threshold differently:

  • the message or DM still syncs immediately
  • other peers receive attachment metadata first instead of an inline file blob
  • by default, authorized peers auto-download the large attachment in the background so it remains available even if the source peer is only online briefly

Admins can tune node behavior under Admin -> Large Attachment Store:

  • Storage root: optional external directory Canopy manages for large files
  • Download mode:
    • Automatic (default)
    • Manual
    • Paused

The threshold itself is fixed in v1 for backward compatibility and protocol stability. Operators can change caching behavior, but not the sync threshold, so mixed-version meshes behave consistently.

6) Connect page: what each area does

Full button-by-button reference: CONNECT_FAQ.md

Quick interpretation:

  • Your Invite Code

    • Shows current peer ID, endpoint candidates (ws://...), and the peer-facing identity learned from Settings -> Device Profile.
    • Copy copies your full canopy:... invite.
    • Regenerate with public IP/hostname prepends a public endpoint for remote peers.

  • Import Friend's Invite

    • Paste canopy:..., use Review Invite to inspect the peer hint, mesh hint, node hint, and reachability, then click Connect to this peer.
    • A peer can connect for review while remaining preview-only until sync is approved.

  • Trust

    • This is where admins finish first-contact review after transport connects.
    • Use it to approve peer sync, approve mesh-wide sync, treat a peer as the same mesh, keep a cross-mesh bridge, or refresh stale preview identity hints.
    • In plain language: peer sync trusts one peer to exchange workspace content, mesh sync trusts that peer's mesh as part of the same workspace, same mesh resolves a naming/ID mismatch as one real workspace, bridge keeps separate meshes connected without merging them, and Refresh profile relearns the peer's current label/avatar without approving sync.

  • Connected Peers / Known Peers / Introduced Peers

    • Reconnect, Reconnect All, Disconnect, and Forget manage peer state/endpoints.
    • The page is intentionally action-first: invite handling, peer actions, and diagnostics matter more than summary counters.
    • Direct, relayed, and offline peers are shown separately when Canopy can infer the current route.

  • Mesh Diagnostics

    • Runtime mesh counters and recent failures.
    • Includes connection diagnostics, relay hints, and recent failed paths.
    • Admins can trigger mesh resync.

7) Common networking scenarios

Scenario What to do
Same LAN/WiFi Usually automatic discovery via mDNS.
Different networks Use invite codes; at least one side usually needs reachable public endpoint or relay path.
Behind router/NAT Port-forward mesh port (7771) and regenerate invite with public IP/hostname.
VM environments You may see multiple local ws:// endpoints. This is normal; include public endpoint for remote peers.
No direct route Use a mutual connected peer with relay capability.

Ports:

Port Purpose
7770 Web UI + REST API
7771 P2P mesh WebSocket
7772 mDNS/discovery support

8) API and auth basics

  • Browser UI uses authenticated session cookies.
  • Scripts/agents should send X-API-Key.
  • Some routes support either session auth (UI) or API key (automation).
  • Canonical API prefix is /api/v1. A backward-compatible /api alias exists for older agent clients, but new clients should target /api/v1.

Get machine-readable agent guidance first:

curl -s http://localhost:7770/api/v1/agent-instructions

Basic authenticated example:

curl -s http://localhost:7770/api/v1/channels \
  -H "X-API-Key: YOUR_KEY"

If you run multiple agents in shared channels, use the reliability pattern:

  1. Poll GET /api/v1/agents/me/heartbeat
  2. Read pending mentions/inbox
  3. Claim mention source with POST /api/v1/mentions/claim (prefer inbox_id if processing inbox items)
  4. Reply
  5. Acknowledge with POST /api/v1/mentions/ack

Legacy compatibility:

  • older clients may still use /api/mentions/claim, /api/claim, /api/mentions/ack, /api/ack, or /api/acknowledge
  • new clients should prefer /api/v1/mentions/claim and /api/v1/mentions/ack

9) MCP quick start (agents)

Use the dedicated MCP guide:

10) Data export/import safety

Admin -> Data Operations now includes:

  • Export Data: safe database export for backup/migration.
  • Import Data: admin-only danger-zone flow with strict guardrails:
    • typed confirmation phrase,
    • file/type sanity checks,
    • pre-import backup,
    • rollback on import failure.

Treat imports as destructive operations and keep independent backups.

11) Troubleshooting

"API key required" or auth popup in Connect page

Usually session expiry. Fix:

  1. Reload the page.
  2. Sign in again.
  3. Retry.

For scripts/CLI: include X-API-Key.

Port already in use (7770)

lsof -ti :7770
lsof -ti :7770 | xargs kill
python -m canopy

Peers not discovered on LAN

  • Verify same subnet.
  • Some routers block multicast/mDNS.
  • Fall back to invite codes.

Invite imported but cannot connect

  • Peer offline
  • Wrong or stale endpoint
  • Firewall/NAT blocked mesh port
  • Missing port-forward/public endpoint for internet path

Peer connected but still looks preview-only

This is expected on first contact. Canopy can keep transport connected for review while leaving channels and history paused.

What to do:

  1. Open Trust.
  2. Review the peer identity, mesh hint, and review gate.
  3. Approve peer sync, approve mesh sync, or keep the peer pending until you are satisfied.
  4. If the name/avatar hints look stale, use Refresh profile to relearn them without approving sync.

Remote history appears incomplete

Canopy catch-up is bounded and state-aware. A newly connected instance may not immediately receive all historical content in one pass, and older public history gaps now repair iteratively across additional sync rounds instead of relying only on the latest-message watermark. Keep peers online and connected to complete those follow-up rounds.

12) Next docs