Skip to content

Orb Quick Start Guide

Installation

Option 1: Build from Source

# Clone and build
cd /home/zayan/Documents/myProjects/orb
go build -o orb .

# Or use make
make build-local

# Move to PATH
sudo mv orb /usr/local/bin/

Option 2: Cross-Platform Build

# Build for all platforms
./build.sh

# Binaries will be in build/ directory
ls build/

Quick Demo (localhost)

Terminal 1: Start Relay

orb relay --listen :8080

Expected output:

Starting Orb relay server...
Listening on :8080

Security notes:
  • The relay server never sees plaintext data
  • All encryption happens at the edges
  • Sessions expire automatically

Terminal 2: Share a Folder

# Create test folder
mkdir -p /tmp/orb-test
echo "Hello from Orb!" > /tmp/orb-test/test.txt

# Share it
orb share /tmp/orb-test --relay http://localhost:8080

Expected output:

╔════════════════════════════════════════╗
║     Orb - Secure Folder Sharing       ║
╚════════════════════════════════════════╝

  Session:  ABC123
  Passcode: 123-456

Share these credentials with the receiver.
Waiting for connection...

Terminal 3: Connect to Share

orb connect ABC123 --passcode 123-456 --relay http://localhost:8080 --tui

You'll see an interactive file browser. Use:

  • ↑/↓: Navigate files
  • Enter: Open directory or download file
  • Backspace: Go to parent directory
  • d: Download selected file
  • q: Quit

Real-World Usage

Share with Remote User

  1. Setup (once):
# Deploy relay on VPS
ssh user@your-vps.com
./orb relay --listen 0.0.0.0:8080
  1. Share (from your machine):
orb share ./my-documents \
  --relay http://your-vps.com:8080 \
  --readonly

  1. Send Credentials (securely):

  2. Send session ID and passcode via Signal/WhatsApp

  3. Never via email or SMS!

  4. Receiver Connects: 

    orb connect SESSION_ID \
  --passcode PASSCODE \
  --relay http://your-vps.com:8080

Common Scenarios

Scenario 1: Share Read-Only

orb share ./project-docs --readonly

Files can be viewed and downloaded, but not modified or deleted.

Scenario 2: Collaborative Editing

# Sharer (read-write)
orb share ./shared-workspace

# Receiver can upload/modify files
# Use with trusted parties only!

Scenario 3: Quick File Transfer

# Share
orb share ./large-video.mp4

# Receiver downloads via TUI
# Session auto-expires after transfer

Keyboard Shortcuts (TUI Mode)

Key Action
↑/↓ Navigate up/down
Enter Open folder or download file
Backspace Parent directory
d Download selected file
/ Search/filter files
q or Ctrl+C Quit

Troubleshooting

"Failed to connect to relay"

Cause: Relay server not running or wrong URL

Fix:

# Check relay is running
curl http://localhost:8080/health

# Or start relay
orb relay --listen :8080

"Authentication failed"

Cause: Wrong passcode or locked session

Fix:

  • Verify passcode is correct
  • Check for typos
  • Session locks after 5 failed attempts
  • Create new session if locked

"Session expired"

Cause: Session older than 24 hours

Fix:

  • Create new session
  • Sessions auto-expire for security

"Failed to read file"

Cause: Permission issues or file deleted

Fix:

  • Check file still exists
  • Verify sharer has read permission
  • Check if share is read-only mode

Security Tips

  1. Strong Passcodes

  2. Let Orb generate random passcodes

  3. Don't reuse passcodes

  4. Share via secure channels only

  5. Read-Only by Default

  6. Use --readonly unless write access needed

  7. Limits damage if receiver is compromised

  8. Session Hygiene

  9. Create new session for each transfer

  10. Verify receiver identity before sharing credentials

  11. Sessions auto-expire after 24 hours

  12. Network Security

  13. Use HTTPS/WSS for relay in production

  14. Deploy relay behind reverse proxy with TLS

  15. Consider VPN for extra security

  16. Data Sensitivity

  17. Orb is secure, but verify relay server trust
  18. For highly sensitive data, run your own relay
  19. Don't share credentials in plaintext

Performance Tips

  1. Large Files

  2. Files download in chunks

  3. Close other applications if memory constrained

  4. Use stable network connection

  5. Multiple Files

  6. Download files individually via TUI

  7. Or batch download by navigating directories

  8. Slow Networks

  9. Orb handles poor connections gracefully
  10. Automatic reconnection on disconnect
  11. Keep-alive prevents timeout on idle

Advanced Usage

Custom Relay Port

orb relay --listen :9090
orb share ./folder --relay http://localhost:9090

Behind Firewall

Both peers can be behind NAT/firewall - relay handles traversal:

# Both peers behind NAT - still works!
# Relay must be on public internet

Multiple Sessions

You can run multiple share sessions simultaneously:

# Terminal 1
orb share ./docs --relay http://relay:8080

# Terminal 2
orb share ./photos --relay http://relay:8080

# Different session IDs, isolated sessions

Monitoring

Relay Server Logs

Relay logs connections (no content):

Session created: ABC123
Sharer connected: session=ABC123
Receiver connected: session=ABC123
Session closed: ABC123

Note: File names and content are never logged!

Connection Status

Check if tunnel is alive:

# From receiver side, connection status shown in TUI
# If tunnel dies, TUI shows error

Getting Help

Command Help

orb --help
orb share --help
orb connect --help
orb relay --help

Version Info

orb version

Debug Mode

# More verbose output
orb share ./folder --relay http://localhost:8080 --debug

What's Next?

Note: Orb is designed for security. Follow best practices for secure file sharing.