Quick Start

This guide walks you through your very first cloud-share transfer — from starting the sender to receiving and verifying a file on another machine.

ℹ️ Info: You need two machines (or two terminal windows) to complete this walkthrough: one acting as the sender and one as the receiver.

Step 1 — Start the sender

On the sending machine, open a terminal and run:

  cloud-share-sender

The sender will:

  1. Check for the devtunnel CLI (auto-install if missing)
  2. Authenticate with Microsoft Dev Tunnels (if not already logged in)
  3. Start a local web server on port 5000
  4. Create a secure Dev Tunnel
  5. Print the public tunnel URL and a fresh secret token (masked as ****last4)
  6. Open the sender web UI in your browser automatically via a one-time token URL

You will see output similar to:

   ██████╗██╗      ██████╗ ██╗   ██╗██████╗
██╔════╝██║     ██╔═══██╗██║   ██║██╔══██╗
██║     ██║     ██║   ██║██║   ██║██║  ██║
██║     ██║     ██║   ██║██║   ██║██║  ██║
╚██████╗███████╗╚██████╔╝╚██████╔╝██████╔╝
 ╚═════╝╚══════╝ ╚═════╝  ╚═════╝ ╚═════╝
         SHARE

Tunnel URL : https://mtszwr0l.uks1.devtunnels.ms:5000
Secret     : ****rTs
Web UI     : http://localhost:5000/?token=a1b2c3d4... (opening in browser...)

ℹ️ Info: The Web UI URL includes a one-time ?token= parameter. This is the sender UI access token (separate from the encryption secret). Your browser is opened to this URL automatically — after the first visit, a secure HttpOnly cookie keeps you authenticated. Do not share this URL; it is only valid on your local machine.

📸 Screenshot needed: quickstart-sender-startup.png Description: Terminal window showing the cloud-share ASCII banner, tunnel URL, and secret token

Step 2 — Note the tunnel URL and secret

Write down or copy two pieces of information from the sender output:

ItemExamplePurpose
Tunnel URLhttps://mtszwr0l.uks1.devtunnels.ms:5000Where the receiver connects
Secret tokenaB3kP9mQ2rTsAuthenticates and decrypts

⚠️ Warning: The secret is generated fresh on every sender start. It is never persisted to disk. Keep it private — anyone with the URL and secret can receive queued items.

Step 3 — Share URL and secret out-of-band

Send the tunnel URL and secret to your recipient through a separate secure channel — for example:

  • A Signal message
  • An encrypted email
  • A phone call (read it aloud)

Do not send the secret through the same channel you are sending the files through.

Step 4 — Start the receiver

On the receiving machine, open a terminal and run:

  cloud-share-receiver

The receiver will prompt you for the tunnel connection if no history exists. On first use it guides you through three quick sub-prompts:

  Tunnel ID: mtszwr0l

Select the DevTunnel region:
❯ uks1    UK South
  usw2    West US 2
  ...

Port (default: 5000): [Enter]

→ https://mtszwr0l.uks1.devtunnels.ms:5000
Enter the secret token: ************

On subsequent runs, the receiver shows a history picker — just arrow-key to the previous connection and press Enter:

  Which tunnel would you like to connect to?

❯  mtszwr0l    ·  uks1    ·  :5000   (today 14:01)
   ✎  Connect to a new tunnel...

Paste shortcut: Pasting a full URL (e.g. https://mtszwr0l.uks1.devtunnels.ms:5000) into the Tunnel ID field skips the region and port sub-prompts automatically.

After entering the tunnel details the receiver will:

  1. Connect to the sender through the Dev Tunnel
  2. Subscribe to the real-time SSE event stream
  3. Start a local web server on port 5001
  4. Open the receiver web UI in your browser automatically

📸 Screenshot needed: quickstart-receiver-startup-prompt.png Description: Terminal showing the receiver prompting for tunnel URL and secret

Step 5 — Send text from the sender UI

The sender browser tab will already be open — the tool launches it automatically to a token-authenticated URL. The sender UI is protected: navigating to http://localhost:5000 directly (without the token) will return 401 Unauthorized. Your browser session was authenticated on startup via the one-time ?token= URL, and the resulting HttpOnly cookie keeps you signed in for the duration of the session.

In the sender browser tab:

  1. Click the Text tab
  2. Type or paste your message into the text area
  3. Click Share

The item appears in the queue table below with status Queued.

📸 Screenshot needed: quickstart-sender-text-tab.png Description: Sender web UI showing the Text tab with a message typed and the Share button

📸 Screenshot needed: quickstart-sender-queue-item.png Description: Sender queue table showing the newly queued text item with Queued badge

Step 6 — Receive in the receiver UI

In the receiver browser tab, the new item appears in the queue automatically (via SSE — no page refresh needed).

  1. Click Receive next to the item
  2. The receiver fetches and decrypts the item
  3. A hash verification modal appears

📸 Screenshot needed: quickstart-receiver-queue.png Description: Receiver web UI showing the queued item appear in real time

Step 7 — Verify the hash

After receiving, a modal displays the SHA-512 hash verification result:

  ✅ Hash verified
Expected : a3f9c2...e8b1d0
Received : a3f9c2...e8b1d0

A green checkmark means the content arrived intact and was not tampered with. If the hashes do not match, the item is automatically deleted from the sender queue and an error is shown.

📸 Screenshot needed: quickstart-receiver-hash-modal.png Description: Hash verification modal showing a green checkmark and matching SHA-512 hashes

Step 8 — Copy or download

  • For text items: click Copy to Clipboard
  • For file items: click Download

That’s it — your content has been securely transferred, end-to-end encrypted, with integrity verified.

📸 Screenshot needed: quickstart-receiver-copy-download.png Description: Receiver UI showing copy and download buttons after successful verification

What’s next?