Automatically upload finished videos to Google Drive

Why spend time configuring rclone?

Chapter 17 covered scriptwriting, narration, screen capture, editing, and burned-in subtitles. Chapter 18 explained where the supporting tools live and why the first download takes so long. The resulting MP4 still sits somewhere under /data/pi-agent/ inside the Pi Agent add-on. Your phone and tablet cannot open that container path directly, so without an upload step you must connect over SSH, find the file, and retrieve it with scp.

• Without rclone: finish the video → open a computer → connect to Home Assistant over SSH → find the output path → retrieve it with scp → send it through a messaging app or upload it to Drive.
• With rclone: finish the video → receive a Google Drive notification on your phone → open the file → share it.

Pi Agent already includes rclone in the add-on container; there is nothing else to install. Run the OAuth authorization wizard once and choose the Google account that rclone may access. The resulting token is stored in /data/pi-agent/rclone/rclone.conf. It survives add-on restarts and upgrades. A Home Assistant backup also includes it when the Pi Agent add-on is selected and the backup completes successfully (see Chapter 20).

What rclone is and why Pi Agent uses it

rclone is a file synchronization tool. Think of it as a command-line counterpart to the Google Drive app. It supports more than 40 storage services, including Google Drive, OneDrive, Dropbox, Box, iCloud Drive, Amazon S3, Alibaba Cloud OSS, SFTP, and WebDAV. The basic form remains the same: rclone copy local-path remote-name:remote-folder.

Why does Pi Agent use rclone instead of a custom Google Drive uploader? There are three main reasons:

• Mature and reliable: rclone has been developed for more than ten years. It already handles details such as token refresh, retrying interrupted transfers, and multipart uploads for large files.
• No lock-in to one storage provider: if you move from Google Drive to OneDrive or Dropbox, create another remote with rclone config and change the destination in Pi Agent.
• Direct transfer: rclone runs on your own Home Assistant host. Files travel from your home to the storage provider you selected; Pi Agent does not relay them through a separate WoowTech cloud service.

Because Pi Agent includes rclone, you do not need to run apt install rclone or manage a separate version. The executable is already in the add-on container. Your only task here is to authorize the Google account that rclone will use.

Why OAuth is safer than entering your password

You may wonder why rclone cannot simply ask for your Google email address and password. The answer is fundamental to the security design of modern online services.

Google no longer permits that approach. The reason is simple: software that receives your Google password could potentially access your entire account—email, Drive files, your YouTube channel, and payment-related services. Even trusted software can be compromised. Handing over the password would be equivalent to handing over the master key to the account.

OAuth (Open Authorization) solves this problem. The process works as follows:

1. rclone starts an authorization request

   On current rclone releases, a headless setup normally gives you an rclone authorize command to run on a trusted computer with a browser. That command opens Google's official authorization page; older builds may instead print a URL. In either case, enter your password only on a genuine Google page whose address and requested account you have checked.

2. Google asks whether rclone may access Drive

   Review the account, application identity, and requested Drive scope before selecting Allow. This is the same delegated-access model used when another service asks to read Google Calendar.

3. Google issues rclone a token

   The token is a credential limited to the scope you approved. It cannot be used as your Google password for unrelated services such as Gmail. You can revoke it at any time from Google Account → Security → third-party connections; once revoked, the stored token can no longer authorize rclone.

4. rclone uses the token for later transfers

   For each upload, rclone presents the token rather than asking for your password again. Your Google password remains with Google throughout the process.

Prerequisite: access the Pi Agent add-on container

The rclone config wizard is interactive, so you must run it in a terminal inside the Pi Agent add-on container. That usually means opening a Home Assistant terminal, identifying the installed container rather than guessing its name, and then entering it.

1. Install Advanced SSH & Web Terminal

   In the Home Assistant sidebar, open Settings → Add-ons → Add-on Store, search for Advanced SSH & Web Terminal, and install it. This commonly used community add-on provides a browser terminal through Open Web UI, so you do not need a separate SSH client on your laptop. Container-management commands require privileged host access; if your terminal add-on hides Docker while Protection mode is enabled, change that setting only if you understand the security impact, and re-enable it after this task.

2. Confirm which environment the terminal opened

   The terminal first opens in the SSH add-on's environment, where you may see Home Assistant system paths such as /config/ and /mnt/ and where host-level management tools may be available. It is not yet the Pi Agent container. Running ls /data/pi-agent/ at this point may return “No such file or directory,” because /data/pi-agent/ belongs to Pi Agent's persistent add-on data rather than the SSH add-on.

3. Discover your installed add-on slug

   Pi Agent's runtime container is named addon_<slug>. A repository-installed slug commonly begins with an eight-character alphanumeric repository hash, such as b9cf5676_woow_ha_pi_agent. The hash is derived from the repository source, so installations that use different repository URLs can have different names; never copy a container name from someone else's system. The safest approach is to verify the installed name. Open Settings → Add-ons → Woow HA Pi Agent → Info. If your Home Assistant version displays a Hostname or Slug, note the value—for example, b9cf5676_woow_ha_pi_agent. Otherwise, do not infer it; discover the running container with the command in the warning below.

4. Enter the discovered Pi Agent container

   Substitute the verified slug in docker exec -it addon_<your-slug> bash; for example, docker exec -it addon_b9cf5676_woow_ha_pi_agent bash. Do not type the example unchanged unless it exactly matches your installation. A prompt such as root@container-id:/# indicates that you are inside the container. Now ls /data/pi-agent/ should show Pi Agent data, including directories such as sessions, models, and rclone.

5. Run the remaining commands inside that container

   The following rclone config, rclone lsd, and rclone config reconnect commands must run inside the Pi Agent container, where the rclone executable and persistent configuration are available. If you see “rclone: command not found,” stop and confirm the prompt and container name before continuing.

The rclone config wizard, one prompt at a time

Once you are inside the Pi Agent add-on container, run rclone config. The exact wording varies slightly by rclone release, but most prompts use their defaults. Read each prompt before pressing Enter.

1. Select n) New remote

   The wizard first lists any existing remotes; the list is empty on a first run. At the e/n/d/r/c/s/q> prompt, enter n and press Enter to create a new remote.

2. Choose a memorable name

   At name>, enter a short name such as gdrive. Pi Agent will use this name in its upload destination. It is only a local label, not your Google account name. Future remotes could be named dropbox or onedrive.

3. Select drive as the storage type

   The wizard lists more than 40 storage backends, each with a number. Find drive (Google Drive), enter its displayed number—or enter drive if the prompt accepts backend names—and press Enter.

4. Enter a client_id and client_secret, or accept the current default

   At Google Application Client Id>, entering your own Google OAuth client is the durable choice. If your bundled rclone release still permits its shared client, pressing Enter accepts that default; do the same at client_secret. Read the 2026 policy warning below before relying on the shared client. The notice says that the shared client will stop working during 2026.

5. Select scope 1 for full Drive access

   Select 1, “Full access all files, excluding Application Data Folder,” if the pipeline must upload into arbitrary folders and inspect existing files. The more restrictive option 3 limits rclone to files it creates or opens through the app; those uploaded files are still visible in the Google Drive app, but rclone cannot freely browse or manage unrelated existing files. Choose the narrowest scope that supports your workflow.

6. Leave service_account_file blank

   For a personal Google account, you normally do not have a service-account JSON file. Leave service_account_file blank and press Enter.

7. Select n for advanced configuration

   At “Edit advanced config?”, select n for an initial setup. Defaults for chunk size, proxy behavior, and SSL work for 99% of typical home installations.

8. Select n for browser auto-configuration on a headless host

   At Use web browser to automatically authenticate rclone with remote?, remember that this is the easiest step to get wrong. Selecting y is intended for a computer on which rclone can launch Firefox or Chrome; selecting y on a headless host can leave it at waiting for code.... Select n because the Home Assistant host has no desktop browser.

9. Follow the headless authorization instruction on a trusted computer

   Current rclone releases print an rclone authorize command. Run that complete command on a trusted computer that has a browser and a compatible rclone version; obtain rclone only from its official distribution channel. Older releases may print a URL such as https://accounts.google.com/o/oauth2/auth?access_type=offline&client_id=...&scope=...&response_type=code. Copy the entire command or URL, including every :, _, and &. Do not use an unrelated online “authorization helper.”

10. Sign in to Google and review the authorization

    Sign in with the Google account you intend to connect. Confirm that the page is on Google's domain, then review the application and requested scope. A privately registered client in testing may show “Google hasn't verified this app.” Continue through Advanced only when you recognize the OAuth client and expected Drive permissions; otherwise cancel and investigate. Current flows return the authorization result to the trusted computer rather than displaying the old out-of-band verification code described in legacy tutorials.

11. Paste the authorization result into the Home Assistant terminal

    After browser approval, the trusted computer prints an authorization result for the waiting rclone wizard. Copy the complete result and paste it at the corresponding token prompt in the Pi Agent terminal. Older bundled versions may instead ask for Enter verification code> and report Got code. When accepted, rclone writes the token to rclone.conf.

12. Select n for Shared Drive unless you use one

    At Configure this as a Shared Drive (Team Drive)?, select n for a normal personal My Drive. Select a Shared Drive only if your organization has granted you access and you deliberately want this remote rooted there. Team Drive is the former name for Shared Drive.

13. Review the summary and save

    Check the summary, including type = drive and the selected scope. At Keep this "gdrive" remote?, enter y only if the values are correct. Back at the main menu, enter q to quit.

Verify that the remote works

Do not assume that a completed wizard means uploads work. While still inside the Pi Agent add-on container, run:

rclone lsd gdrive:

This lists directories in the root of the gdrive remote. It should show folders from the configured My Drive or Shared Drive root, for example:

          -1 2024-03-15 08:22:14        -1 Albums
          -1 2025-06-20 14:11:03        -1 Work Backups
          -1 2026-01-08 22:45:56        -1 Home Videos

A directory listing confirms read access. No output and no error can also be valid if the configured root contains no directories; create a folder and repeat the check if you need an unambiguous result.

If an error appears, use the troubleshooting section below. Three common cases are:

Next, use a temporary file to test write access. Before running this fixed-name example, confirm that the Drive root does not already contain test.txt; otherwise, substitute a unique filename in both commands so that the test cannot replace an existing file:

echo "hello from pi agent" > /tmp/test.txt
rclone copy /tmp/test.txt gdrive:

Check the Google Drive app's Recent view and confirm the contents of test.txt. Only after you have verified the remote copy should you delete the test file from Drive. This test does not delete the local file.

Connect gdrive to the pitch_video pipeline

Configuring rclone establishes the remote, but Pi Agent still needs an upload destination such as gdrive:Some folder. The supported setting can vary by pitch_video Skill version. Read that installed version's SKILL.md, README, and configuration example before changing anything; do not assume that a field from another version exists.

First create a dedicated folder in Google Drive, such as PiAgent/Videos. rclone can create missing destination directories during a copy, but creating the folder yourself lets you verify its location and sharing permissions before any automated upload.

Open the pitch_video Skill's SKILL.md or README and look for documented fields such as upload_to or output_upload. Common implementations include the following:

Use a trailing slash / in all three forms. It makes the destination's directory intent clear and is recommended for consistency. With rclone copy, however, gdrive:PiAgent/Videos is also a directory path; renaming a single file requires copyto. Never replace copy with sync merely to upload a file, because sync can delete destination files that are absent from the source.

After saving a supported configuration, run the complete video pipeline from Chapter 17. Its final stage should produce a log similar to:

[push_drive] Uploading final.mp4 (42MB) to gdrive:PiAgent/Videos/
[push_drive] Transferred: 42.1 MiB / 42.1 MiB, 100%, 3.2 MiB/s
[push_drive] Uploaded final.mp4 successfully in 13s

Then verify the file in Drive—its name, size, and playability—not just the presence of a success-looking log line. If no push_drive log appears, confirm that the upload_to setting was saved in the documented location and that the remote name matches exactly, including case. Do not delete the local output unless the upload process returned success and you independently verified the remote file.

Where the token is stored—and how backups affect it

After OAuth succeeds, rclone stores the remote configuration and token here:

/data/pi-agent/rclone/rclone.conf

The relevant portion resembles this example:

[gdrive]
type = drive
scope = drive
token = {"access_token":"ya29.a0Af...","token_type":"Bearer","refresh_token":"1//0e...","expiry":"2026-08-14T15:30:00.000000Z"}
team_drive =

The refresh_token allows rclone to obtain new short-lived access tokens without repeating interactive OAuth. It is a long-lived credential. Anyone who obtains a usable copy of rclone.conf may be able to access data within the granted Drive scope until you revoke that authorization.

The /data/pi-agent/ tree is persistent data for the Pi Agent add-on. That has two important consequences:

1. Add-on upgrades should preserve it

   See Chapter 21 before upgrading. An upgrade replaces the add-on's packaged filesystem, but persistent data under /data/ remains. Under normal conditions, restarting or upgrading Pi Agent therefore does not require OAuth again.

2. A Home Assistant backup can include it

   Chapter 20 covers backup selection and restore verification. A Home Assistant backup can package an add-on's /data/, including rclone.conf, when the Pi Agent add-on is selected and the backup finishes successfully. After restoring that add-on data on the same or a new host, the token should return with it, but test rclone lsd and a harmless upload rather than assuming the restore worked.

The following events determine whether OAuth must be repeated:

Use Dropbox, OneDrive, or S3 instead

rclone supports more than 40 storage services, and adding another one usually begins with another run of rclone config. You can also keep several remotes at once—for example, one copy in Google Drive and another in Dropbox. Two copies improve redundancy, although they are not a complete backup strategy unless you also define retention and test recovery.

1. Run rclone config again

   Select n for a new remote and choose a clear name such as dropbox, onedrive, or s3.

2. Select the matching storage backend

   Select dropbox for Dropbox, onedrive for OneDrive, or s3 for an S3-compatible service, followed by the correct provider such as AWS or Cloudflare R2. Each wizard asks for different information:

   • Dropbox: the OAuth flow resembles Google Drive. On a headless Home Assistant host, select n for browser auto-configuration and complete the printed authorization instruction on a trusted computer.
   • OneDrive: select the account and drive type offered by your current wizard. A personal onedrive.com account and an organizational Microsoft 365 account can present different choices.
   • S3: many providers use an access_key_id and secret_access_key rather than OAuth. For AWS, create least-privilege credentials through IAM; do not use account-root credentials.

3. Change pitch_video's upload_to destination

   Replace gdrive: with the documented destination, such as dropbox:, onedrive:, or s3:mybucket/. Test the exact remote first—for example, with rclone lsd dropbox:—and then perform a harmless upload.

4. For two destinations, run and verify two copies

   A Skill script can run rclone copy final.mp4 gdrive:PiAgent/Videos/ and rclone copy final.mp4 dropbox:PiAgent/Videos/. Each transfer consumes its provider's quota and can fail independently. Check both exit statuses and both remote files before reporting overall success or deleting the local source.

Common pitfalls

1. The authorization instruction is truncated or opens as a search

   An older rclone authorization URL may be 200–400 characters long and contain many &, :, and _ characters; current releases may print an even longer rclone authorize command. Missing a single character breaks the flow. In Advanced SSH Web UI, triple-click the complete line and press Ctrl+C. Paste a URL into the browser's address bar, not a search field; on mobile, use Paste and go. Prefer a private, end-to-end transfer method over emailing an authorization command or URL to yourself, because it is sensitive until the flow ends.

2. Google says that it has not verified the application

   This warning can appear for an OAuth client that is unverified or still in testing; it is not proof that every such prompt is safe. Check that you started from the expected rclone command, the page is genuinely hosted by Google, the account is correct, and the requested Drive scope matches your choice. Only then should you open Advanced and choose Continue to rclone. If any detail is unfamiliar, cancel. Creating your own client_id does not automatically remove the warning: you must also configure the consent screen and test users, and broader public use may require Google's verification process.

3. The upload fails with quota exceeded

   A standard Google account commonly includes 15 GB shared by Drive, Gmail, and Google Photos; confirm the current allowance for your account. If it is full: (a) remove unneeded files, including large Gmail attachments; (b) use Dropbox or OneDrive as described in the previous section; (c) consider additional storage, but check current official prices first—the examples available when this guide was written were about TWD 700 per year for 100 GB, TWD 900 for 200 GB, and a few cents per GB for S3 or R2, but prices vary by country and can change; and (d) if the Skill supports cleanup, delete local output only after a successful exit status and independent verification of the remote file.

4. The token fails with 401 after a long period of inactivity

   Refresh tokens are long-lived, not guaranteed to last forever. They can stop working after revocation, OAuth-client changes, long inactivity under some policies, account-security actions, or other provider limits. Typical errors include oauth2: token expired and 401 Unauthorized. Review Google Account security activity first, then run rclone config reconnect gdrive: inside the Pi Agent add-on container and complete the current headless OAuth flow. The command updates the token in rclone.conf.

5. rclone lsd is slow or appears to hang

   Use rclone lsd gdrive: -vv to distinguish network retries from a large directory listing. ping accounts.google.com can reveal gross connectivity problems, but some services block or deprioritize ping, so it is not a conclusive API test. Restarting a faulty router may help; changing DNS to 8.8.8.8 is not a universal fix and should comply with your privacy and network policies. A Drive root containing tens of thousands of entries can also take dozens of seconds to enumerate. If PiAgent already exists, rclone lsd gdrive:PiAgent/ limits the listing to that folder.

6. docker exec does not change the prompt, or rclone is still not found

   The docker exec command may have failed, targeted the wrong container, or been blocked by the SSH add-on's permissions. Where the Home Assistant ha CLI is available, it can inspect add-on metadata but does not enter the container. Run docker ps --format '{{.Names}}' | grep pi_agent and verify the exact result, such as addon_b9cf5676_woow_ha_pi_agent, before trying again. ha addons info <your-slug> can provide additional metadata. Do not guess at Podman or Docker commands. If management commands are unavailable, consult the terminal add-on's host-access and Protection mode documentation, or use an add-on-provided web terminal only if its Info page explicitly offers one.

7. The video finishes, but push_drive never runs

   Check three possibilities: (a) compare the configuration with the previous section and that exact version's documentation; (b) if the installed Skill does not recognize upload_to, it may predate automatic uploads—review its CHANGELOG and use its documented upgrade procedure rather than blindly pulling files from GitHub; or (c) push_drive.sh may have skipped the stage after an rclone preflight failure. Read the complete execution log before changing configuration.

8. OneDrive rejects a name that Google Drive accepted

   OneDrive applies stricter naming rules to characters such as :, ?, *, <, >, and |. rclone normally encodes characters that a backend cannot store, but results depend on backend and encoding settings. The option --onedrive-server-side-across-configs controls server-side operations between OneDrive configurations; it does not repair invalid filenames and should not be added for this problem. A name such as “Living room: turn on the lights first?” is less portable than living_room_lights_20260814.mp4. Generate conservative alphanumeric names with underscores when files must work across providers.

FAQ