4. Remotes¶

A remote is a named sync target for the active checkout. Transfers are delegated to rclone, so anything rclone can reach, forest can sync to.

For this tutorial the remote is a plain directory on your own disk — any absolute path works as a remote URL, which is what makes the whole walkthrough runnable without credentials:

mkdir -p ~/forest-remote
forest remote add origin ~/forest-remote

Added remote 'origin' -> /home/user/forest-remote

Local directory (this tutorial)S3SFTP

forest remote add origin ~/forest-remote

Any absolute path is treated as a local remote. Great for the tutorial, for air-gapped machines, and for NAS mounts.

forest remote add origin s3://my-bucket/prefix --region us-east-2

Also accepts --endpoint for S3-compatible stores and --profile for a named auth profile. Credentials come from your normal AWS setup; forest rejects URLs with embedded credentials.

forest remote add origin sftp://user@host/path --key-file ~/.ssh/id_ed25519

--known-hosts pins a known_hosts file for strict host checking.

Remote-first workflows

Remotes can be added before any local binding exists — useful when your data starts out remote-only and you plan to pull it down later.

Managing remotes¶

forest remote list

  origin    /home/user/forest-remote    [local]
Run: forest remote use origin

forest remote show origin

Name:      origin
URL:       /home/user/forest-remote
Type:      local

That Run: forest remote use origin hint is optional right now: while exactly one remote is configured, forest uses it automatically. remote use only becomes mandatory once a second remote exists — and the choice of active remote is per-machine, stored in the gitignored local.yaml.

forest remote use origin       # select the active remote (optional today)
forest remote remove origin    # drop a remote        (don't run this now!)

What just happened on disk¶

The remote definition is shared — it lands in the committed forest.yaml next to the stages from chapter 3:

.forest/checkouts/survey/forest.yaml

project: survey
remotes:
  origin:
    url: /home/user/forest-remote
stages:
  raw:
    remote_path: survey/raw
  processed:
    remote_path: survey/processed
    sync_by: directory

Note the remote_path defaults: each stage lands under <checkout>/<stage> on the remote, so one bucket or directory can host many checkouts without collisions.

Recap: a remote is a named rclone target; provider options ride along in shared config; a single remote is used automatically.

Next: move some bytes — push, pull & status.