Buckets keep your folders in your backends

Its paths

Paths are in ~/Link/Personal or an agent's files folder (~/Link/Agents/<name>/Home). A relative path starts from the current folder when you're in one of them, and from ~/Link/Personal otherwise. pull, remove and link create take globs, so quote them and use ** to span folders.

What backend create makes

backend create makes a private bucket for your files, once per backend, and tests the keys. If a test fails after the bucket is made, it deletes the bucket again, or says which one it couldn't.

AWS and Google Cloud

On AWS and Google Cloud a bucket signs in as a cloud account from lnk cloud connect, the same one your boxes there use. backend create connects it first when there's none, asking what lnk cloud connect asks. A service account connects there, with its key: lnk cloud connect gcp --name gcp-ci --credential-file key.json.

--encrypt

Add --encrypt to encrypt your files and their names before upload. Link makes a password and shows it once, and if you lose it, nobody can read the files.

Back up each agent's files

Each agent's files folder goes to a bucket of its own in every backend, made on its first push and always encrypted, with one password per agent. The same commands work on it, but pull and clean refuse while the agent runs, or when Link can't tell, so stop it first.

lnk bucket push ~/Link/Agents/work/Home
lnk agent stop --agent work && lnk bucket clean ~/Link/Agents/work/Home

Keep an agent's conversations and notes in its bucket

An agent keeps its collections (instructions, skills, memory, conversations, schedule) where its spec prefers, among the places its machine supports (Agent Spec). With bucket, they're objects in its encrypted bucket, under .link/agent/, apart from its files: any machine connected to the bucket reads them as it left them.

# ~/.lnk/agents/work/agent.toml
[storage]
conversations = "bucket"

A hosted team's folder

Push and pull also discover the owned hosted teams, as the harness plugin answers bucket.folders (Bucket Contract). Their local folder is ~/Link/Teams/<team>/Shared; their permanent bucket-folder ID is qualified as team:<id> so it cannot name an agent's Home.

See what's where

Each file gets one mark per backend: ✓ checked, A checked in an archive tier, ? not checked, ≠ differs, ✗ missing. tree works offline, and --refresh finds files pushed from another machine.

lnk bucket tree --level 2
lnk bucket tree photos --refresh   # list the backends again first

Use a bucket from another machine

backend connect takes the same options as backend create but makes nothing, and stops if the bucket isn't there. lnk bucket backend list --json on the first machine shows each bucket's name.

lnk bucket backend connect aws --bucket local-link-a1b2c3d4e5f6
lnk bucket backend connect folder --path /Volumes/MyDrive --bucket local-link/personal
lnk bucket backend connect aws --bucket lnk-files-0123 --agent-bucket lnk-agents-0123 --agent main  # asks for the password of the agent

Archive old files

Archive tiers cost about $1 per TB a month instead of about $20, and reading files back costs money. They exist on AWS (S3 Glacier Deep Archive) and Google Cloud (GCS Archive), and lnk asks before archiving or restoring.

lnk bucket push old/scans --archive

--expires, --auth and --backend

--expires <time> is 30m, 12h, 3d, at most 7d, the default. With --auth, visitors need a user:password, which it asks for, or reads from LNK_AUTH: never the command line, which other users can see. --backend <name> links only to copies in that backend.

What a link shares

A link shares only your files in ~/Link/Personal, from AWS and S3 backends, outside archive tiers. It uses what the manifest knows, so run tree --refresh first for files pushed from elsewhere.

Its paths and its end

A file keeps its path from where the pattern starts, so photos/2019/*.jpg shares beach.jpg and photos/2019 shares 2019/beach.jpg. link delete can't recall URLs already handed out, and they work until the link would have expired.

Without the accounts plugin

A link lives on your relay, signed for by the accounts plugin. A release of Link without that plugin has no share links, and lnk bucket link create says so plainly rather than offering to install it, while backups, pushes and pulls work as ever.

Download a share

To download a share with Link installed, pull its URL: it saves the files into the current folder, each checked against its size.

lnk bucket pull --link https://<user>.<domain>/b/0123456789abcdef01234567

Remove from your backends

remove deletes the copies in every backend, or only in those you give with --backend, and keeps the files here. It takes only files and folders, and refuses a backend's name.

lnk bucket remove old/drafts --backend gcp

Disconnect or delete a backend

backend disconnect prints the backend connect command that brings the backend back, and asks only when the backend holds a file's only copy. backend delete deletes the buckets lnk bucket backend create made, your files' and your agents', and on a folder backend Link's folders in it. It asks first, and refuses a path.

lnk bucket backend disconnect gcp   # forget it and its keys, and delete nothing in it
lnk bucket backend delete aws       # delete its buckets and everything in them, then forget it

Removing it

lnk plugin remove bucket and lnk uninstall keep this folder, and neither deletes anything in your backends. lnk uninstall --delete buckets deletes it, along with the only copy of the encryption passwords Link made, so save them first.