WAIIDE Workspace Sharing via JupyterHub

Calliope Integration: This component is integrated into the Calliope AI platform. Some features and configurations may differ from the upstream project.

WAIIDE now supports sharing your WAIIDE workspace with others through JupyterHub’s token-based sharing system, similar to how Jupyter notebooks can be shared.

Overview

The sharing feature allows you to:

Generate secure, time-limited access tokens
Share your entire workspace or specific files
Control permissions (View Only, Full Access, Terminal Access)
Revoke access at any time
Share via email or direct links

How It Works

The sharing system integrates WAIIDE’s native sharing interface with JupyterHub’s authentication system:

Token Generation: Creates JupyterHub API tokens with appropriate scopes
URL Construction: Builds shareable URLs that include the token
Access Control: Recipients authenticate using the shared token
Automatic Expiration: Tokens expire based on your settings

Prerequisites

Running in a JupyterHub environment with WAIIDE
Valid JupyterHub API token (automatically provided)
Appropriate permissions to create sharing tokens

Using the Sharing Feature

Method 1: Command Palette

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Search for “Share” commands:
- WAIIDE: Share Workspace - Share entire workspace
- WAIIDE: Share Current File - Share currently open file
- WAIIDE: Share Selection - Share selected text

Method 2: Context Menus

Right-click in editor → Share Current File / Share Selection
Right-click in Explorer → Share Current File

Method 3: Status Bar

Click the Share button in the status bar (bottom right)

Method 4: WAIIDE Native Sharing

Use WAIIDE’s built-in sharing via the title bar or command palette
The JupyterHub provider will appear as “Share via The Hub”

Permission Levels

View Only

Recipients can view files and browse the workspace
Cannot edit, save, or run commands
Ideal for WAIIDE reviews or demonstrations

Full Access

Recipients have complete access to edit files
Can save changes and modify the workspace
Cannot access terminal or run commands

Terminal Access

Full workspace access plus terminal/command execution
Use with extreme caution - recipients can run any command
Only share with trusted collaborators

Expiration Options

1 hour - Quick collaboration sessions
4 hours - Extended work sessions
24 hours - Daily collaboration
1 week - Long-term project sharing
Never - Permanent access (revoke manually when done)

Sharing Workflow

Select what to share (workspace, file, or selection)
Choose permission level (View Only, Full Access, Terminal Access)
Set expiration time (1 hour to never)
Choose sharing method:
- Copy Link - Copy URL to clipboard
- Open in Browser - Open the shared workspace
- Share via Email - Create pre-filled email

API Endpoints

The sharing feature exposes REST API endpoints:

`POST /api/share/create`

Create a new share token

{
  "permission": "View Only",
  "expires_in": 3600,
  "note": "WAIIDE Share - View Only",
  "file": "optional/file/path.js",
  "line": 42,
  "col": 0
}

`GET /api/share/info`

Get sharing environment information

{
  "sharing_available": true,
  "environment": "jupyterhub",
  "user": "username",
  "server_name": "my-server"
}

`DELETE /api/share/revoke`

Revoke all sharing tokens (future implementation)

Security Considerations

Token Security

Tokens are scoped to specific permissions
Tokens automatically expire based on settings
Tokens can be revoked at any time

Network Security

All sharing happens through JupyterHub’s secure proxy
No direct WAIIDE server exposure
Inherits JupyterHub’s SSL/TLS configuration

Audit Trail

Share token creation is logged in JupyterHub
Token usage appears in JupyterHub logs
Each token includes descriptive notes

Best Practices

For WAIIDE Reviews

Use View Only permission
Set short expiration (1-4 hours)
Share specific files rather than entire workspace

For Pair Programming

Use Full Access permission
Set session-appropriate expiration
Communicate via voice/video alongside sharing

For Demonstrations

Use View Only permission
Share specific files or selections
Consider screen sharing for better presentation control

For Remote Development

Use Terminal Access only with trusted collaborators
Set reasonable expiration times
Monitor and revoke when collaboration ends

Troubleshooting

“Sharing not available”

Ensure you’re running in JupyterHub environment
Check that JUPYTERHUB_API_TOKEN is set
Verify you have permission to create tokens

“Failed to generate share link”

Check JupyterHub server connectivity
Verify your JupyterHub user permissions
Check JupyterHub logs for API errors

“Failed to parse URL from /user/…/api/share/create”

This error indicates the share API endpoint URL construction issue. Fixed in latest version by:

Constructing absolute URLs with protocol and host from window.location
Ensuring share API handlers are registered in jupyter_server_config.py

If you see this error:

Rebuild the WAIIDE container to include the latest WAIIDE changes
Ensure ShareCreateHandler and ShareInfoHandler are registered
Check browser console for the full error details

Recipients can’t access shared link

Verify token hasn’t expired
Check that recipient has appropriate JupyterHub access
Ensure the share URL is complete and unmodified

Authentication still required despite share token

Ensure the token has correct scopes for the server (including named server scopes)
Check that JupyterHub accepts tokens in URL query parameters
Verify the service prefix matches the actual server URL path

Revoking Shares

Revoke All Shares

Command Palette → “WAIIDE: Revoke All Shares”
Confirm the action (this immediately blocks all recipients)

Individual Token Management

Use JupyterHub’s admin interface
View tokens at /hub/token (if permitted)
Individual revocation coming in future version

Integration with Remote Development

The sharing feature can be extended to support remote development containers:

Future Enhancements

DevContainer Sharing - Share development environments
Port Forwarding - Share running applications
Real-time Collaboration - Live cursor sharing
Version Control Integration - Share Git branches/commits

Development

Extension Structure

calliope-WAIIDE-agent/src/
├── jupyterHubShareProvider.ts    # Core sharing logic
├── shareCommands.ts              # WAIIDE commands
└── extension.ts                  # Registration

API Server Integration

scripts/api_server.py
├── handle_share_api()           # Main API handler
├── handle_create_share()        # Token creation
└── get_scopes_for_permission()  # Permission mapping

Environment Detection

The extension automatically detects JupyterHub environments by checking:

JUPYTERHUB_API_TOKEN - API access token
JUPYTERHUB_USER - Current username
JUPYTERHUB_SERVICE_PREFIX - URL prefix

Configuration

No additional configuration is required. The feature uses environment variables provided by JupyterHub:

JUPYTERHUB_API_URL - Hub API endpoint
JUPYTERHUB_API_TOKEN - Authentication token
JUPYTERHUB_USER - Current user
JUPYTERHUB_SERVICE_PREFIX - URL prefix for this instance
JUPYTERHUB_SERVER_NAME - Named server identifier

Compatibility

JupyterHub: Version 1.4+ with token API support
WAIIDE: Any version with sharing API (1.84+)
WAIIDE: All versions with JupyterHub integration
Browsers: All modern browsers supporting JupyterHub

This sharing feature transforms WAIIDE in JupyterHub into a collaborative development platform, making it easy to share workspaces just like sharing Jupyter notebooks.

WAIIDE Troubleshooting WAIIDE_TECHNICAL_BLUEPRINT_V1