Security Best Practices link

Cloud Share is designed to be secure by default, but the security of any transfer ultimately depends on how you use it. Follow these practices to ensure your transfers remain private and tamper-proof.

Use CLOUDSHARE_SECRET to avoid exposing the secret in the process list link

Passing the secret as a --secret flag puts it in your shell history and the process argument list visible to ps aux on the same machine. Use the CLOUDSHARE_SECRET environment variable instead:

  # Sender — overrides the auto-generated random secret
export CLOUDSHARE_SECRET="aB3kP9mQ2rTs"
cloud-share-sender

# Receiver — skips the interactive prompt entirely
export CLOUDSHARE_SECRET="aB3kP9mQ2rTs"
cloud-share-receiver
  

When CLOUDSHARE_SECRET is set on the receiver, the connection starts immediately without a prompt — useful for scripts and CI pipelines.

⚠️ Warning: Ensure you unset CLOUDSHARE_SECRET (or close the shell) after the session to prevent the value persisting in the environment.

Share the secret through a separate secure channel link

The tunnel URL and the secret token together are the keys to your transfer. Never send them together through an insecure channel.

✅ Do:

• Share the secret via Signal, WhatsApp, or another end-to-end encrypted messenger
• Read it aloud over a phone or video call
• Send it via an encrypted email (PGP/S-MIME)
• Use a password manager’s secure sharing feature

❌ Don’t:

• Include the secret in the same email or chat message as the tunnel URL
• Post either the URL or secret in a public Slack channel, GitHub issue, or document
• Send it as plaintext in a regular email

⚠️ Warning: Anyone who has both the tunnel URL and the secret can receive all queued items, including ones you haven’t sent yet. Treat the secret like a password.

Stop the sender after the transfer is complete link

The sender’s tunnel stays active and the secret remains valid for as long as the process is running. Once your recipient has received everything they need:

1. Stop the sender with Ctrl+C
2. Confirm the terminal session has exited

Stopping the sender:

• Closes the Dev Tunnel (the URL immediately becomes unreachable)
• Invalidates the secret
• Clears all queued items from memory

  # The sender runs until you press Ctrl+C
cloud-share-sender
# ... transfer completes ...
^C   # Stop the sender
  

Use cloud-share for one-time transfers link

Cloud Share is designed for ephemeral, one-time transfers — not as a persistent file server. Each sender run generates a new secret, and the queue is not persisted to disk.

✅ Intended use:

• “I need to send you this file right now”
• One-off sharing between two machines you control
• Transferring credentials or secrets to a new machine during setup

❌ Not intended for:

• Leaving the sender running indefinitely as a file server
• Sharing files with many recipients over an extended period
• Replacing a proper file-sharing or document management system

Use a zip password for sensitive files link

When sharing particularly sensitive files (private keys, certificates, credential files, financial documents), use the Zip Bundle feature with a password:

1. Use the Zip Bundle tab instead of the File tab
2. Enter a strong password in the zip password field
3. Share the zip password with your recipient via a different channel than the secret token

This provides double encryption:

• AES-256-GCM encrypts the zip during transport (keyed to session secret)
• AES-256 encrypts the zip entries themselves (keyed to your password)

Even if someone recovers the decrypted zip bundle, they cannot access the files without the password.

⚠️ Warning: If you forget the zip password, the files cannot be recovered. The password is not stored anywhere in the system.

Understand where the secret appears link

The secret token appears in:

• The sender’s terminal output (startup banner, masked as ****<last-4> by default)
• The Authorization: Bearer HTTP header on every API call — never in URLs or query strings

The secret is fully protected in transit by HTTPS/TLS. The Authorization header is encrypted by the TLS layer — it is not visible to network observers between the sender and the Dev Tunnel relay, and it does not appear in access logs, browser history, or proxy logs.

However, the secret may appear in:

• Shell history if passed via --secret flag: prefer CLOUDSHARE_SECRET env var instead
• Server-side logs if verbose logging is enabled on the sender

For most use cases this is acceptable. If you are in a highly sensitive environment:

• Use CLOUDSHARE_SECRET environment variable rather than --secret flag
• Clear the receiver’s saved session file after the transfer

Rotate the secret by restarting the sender link

If you suspect the secret has been compromised (e.g. accidentally shared in a chat), simply restart the sender:

  # Ctrl+C to stop
^C

# Start again — new secret generated automatically
cloud-share-sender
  

A new secret is generated on every start. The old URL and secret are immediately invalid.

Understand the token scope and lifetime link

Clear saved receiver session history if needed link

The receiver saves up to 5 recent tunnel connections (tunnel ID, region, port, and secret) to receiver-session.json. Entries older than 7 days are automatically pruned. On shared machines or after sensitive transfers, you may want to clear the file manually:

  # Windows
del "%APPDATA%\CloudShare\receiver-session.json"

# macOS / Linux
rm ~/.config/CloudShare/receiver-session.json
  

ℹ️ Info: The saved secrets in receiver-session.json are from previous sessions — they are already invalid because those senders have stopped. However, the tunnel IDs (which partially reveal what you connected to) may remain. Clear the file on shared machines after sensitive transfers.

ℹ️ Info: The file is restricted to 600 permissions (owner read/write only) on macOS and Linux — other users on the same machine cannot read it.

DevTunnels authentication link

The sender authenticates with Microsoft Dev Tunnels using your Microsoft or GitHub account. This login is saved to preferences.json. To revoke it:

  cloud-share-sender --reset
  

This clears the saved OAuth tokens and forces re-authentication on the next run. You can also revoke the DevTunnels app’s access from your Microsoft or GitHub account settings.