Handler Storage Gdrive

{
  "handlers": {
    "gdrive": {
      "client_id": "${GDRIVE_CLIENT_ID}",
      "client_secret": "${GDRIVE_CLIENT_SECRET}",
      "folder_id": "root",
      "rclone_remote_name": "gdrive"
    }
  }
}

Configuration Fields:

• client_id: OAuth 2.0 Client ID from Google Cloud Console (required)
• client_secret: OAuth 2.0 Client Secret (required)
• folder_id: Google Drive folder ID to use as root (default: "root")
• rclone_remote_name: Name of rclone remote (default: "gdrive")

Security Best Practices:

• Use environment variables for OAuth credentials: ${GDRIVE_CLIENT_ID}
• Never commit OAuth secrets to version control
• Use OAuth2 for authentication (no service account needed)
• Rotate OAuth tokens via rclone config reconnect
• Limit OAuth scopes to drive.file or drive (full access)

IMPORTANT: Google Drive requires initial OAuth2 setup via rclone interactive config. See docs/oauth-setup-guide.md for detailed instructions.

Parameter Flow:

• Agent loads configuration and expands env vars
• Skill receives: operation + rclone remote + folder + paths
• Skill invokes script with all parameters
• Script executes rclone with Google Drive backend
• Skill returns structured JSON result

{
  "success": true,
  "message": "Operation completed successfully",
  "url": "https://drive.google.com/file/d/FILE_ID/view",
  "size_bytes": 1024,
  "checksum": "sha256:abc123..."
}

File Upload:

{
  "success": true,
  "message": "File uploaded to Google Drive successfully",
  "url": "https://drive.google.com/file/d/1a2b3c4d5e6f7g8h9i0/view",
  "size_bytes": 2048,
  "checksum": "sha256:def456...",
  "file_id": "1a2b3c4d5e6f7g8h9i0"
}

Shareable Link:

{
  "success": true,
  "message": "Shareable link generated",
  "url": "https://drive.google.com/file/d/FILE_ID/view?usp=sharing",
  "type": "shareable"
}

Installation:

# macOS
brew install rclone

# Linux
curl https://rclone.org/install.sh | sudo bash

# Check installation
rclone version

Prerequisites

1. Google Cloud Project with Drive API enabled
2. OAuth 2.0 Client ID (Desktop application type)
3. rclone installed on your machine

Quick Setup

See docs/oauth-setup-guide.md for complete step-by-step instructions.

Summary:

1. Create OAuth credentials in Google Cloud Console
2. Run rclone config and create new remote
3. Select Google Drive backend
4. Provide Client ID and Client Secret
5. Complete OAuth flow in browser
6. Configure fractary-file to use the rclone remote

Token Management

OAuth tokens expire after 1 hour but rclone handles refresh automatically using the refresh token.

Manual refresh (if needed):

rclone config reconnect gdrive:

Scopes

• drive.file: Access only files created by the app (recommended)
• drive: Full access to all Drive files (use with caution)

See docs/oauth-setup-guide.md for detailed security considerations.

Why rclone?

• Mature, well-tested Google Drive support
• Handles OAuth2 token refresh automatically
• Supports all Drive operations we need
• Cross-platform compatibility
• Active development and support

rclone Remote Configuration: The handler expects an rclone remote configured with:

• Name: gdrive (configurable via rclone_remote_name)
• Type: drive (Google Drive backend)
• OAuth2 token stored in rclone config

Configuration Location:

• Linux/macOS: ~/.config/rclone/rclone.conf
• Windows: %USERPROFILE%\.config\rclone\rclone.conf

Verifying Setup:

# Test rclone remote
rclone lsd gdrive:

# Check configuration
rclone config show gdrive