Concepts
The five nouns the whole product is made of, and how they relate.
View as MarkdownEverything in saved.sh is built from five objects. Learn what each one is and the rest of the documentation reads itself.
Workspace ─► Backup ─► Run ─► Artifact
tenant definition execution stored fileEach arrow is ownership. A workspace owns its backups, a backup owns its runs, and a successful run produces exactly one artifact. A worker sits beside that chain: it is the credential that lets a machine you control execute a run.
Workspace
The tenant. Members, permissions, quotas and billing all belong to one workspace.
Backup
A definition: what to copy, on what schedule, kept for how long. Not the copy itself.
Run
One execution of a backup. Succeeds or fails, and says which.
Artifact
What a run produced. Sized, retained under a policy, and downloadable.
Worker
A credential that lets a machine you control claim work. Not a machine.
Two cross-cutting ideas complete the picture:
Retention
The one setting that bounds what you store, fixed when the backup is created.
Quotas
Per-workspace limits, checked before anything is created.
The distinction that causes the most confusion
A backup is not a copy of your data. It is the definition that says what to copy. The copies are artifacts.
That matters the moment you act on one:
| You want to | You act on |
|---|---|
| Change a schedule, a source, or a key | The backup |
| Stop it running for a while | The backup (pause) |
| Download or restore data | An artifact |
| Delete one copy | An artifact |
| See why last night failed | A run |
"Delete the backup" almost never means what people intend, and it is refused while artifacts still exist for exactly that reason.
Words we deliberately do not use
Vocabulary here is chosen once and kept, because two words for one thing costs more than it saves.
| Not used | We say | Why |
|---|---|---|
| Project | Backup | It named the definition and read like a container |
| Job | Run | Collides with cron's recurring series and CI's unit-inside-a-run |
| Agent | Worker | It is a credential, not an autonomous thing |
| Key, for a worker | Token | "Key" is reserved for encryption keys |
That last one is worth internalising. In these docs:
- A key is your PGP encryption key. We hold the public half only.
- A token authenticates a worker.
- An API key authenticates automation, and is the one place the word is overloaded.
Where things live
| Object | Held by |
|---|---|
| Backup definitions, artifacts, runs, audit | Us |
Source credentials, local backups | Your worker's config file |
Source credentials, cloud backups | Our vault |
| The private encryption key | You, only |
| Members and roles | Our identity provider |
| Artifact bytes | Our storage, your buckets, or both |