Skip to main content

Garage

@thomas/garagev2026.10.11.1· 1mo agoBEHAVIORS
01README

Control-plane administration of a Garage (S3-compatible object store) cluster through its Admin API v2 (bearer token). Reads cluster health, buckets, access keys, and the full key×bucket permission matrix. Creates, updates and deletes buckets; manages aliases; creates, imports, updates, rotates and deletes access keys; and grants or revokes read/write/owner permissions. Never touches S3 object data; delete and revoke methods verify the target by id first.

02Behaviors1
@thomas/garagev2026.10.11.1garage.ts

Global Arguments

ArgumentTypeDescription
endpointstringBase URL of the Garage Admin API, e.g. http://garage-host:3903 or an HTTPS
adminTokenstringGarage [admin] admin_token (Bearer). Supply via vault:
s3Region?stringS3 region label this cluster advertises (informational; echoed in output)
fn cluster_health()
Fetch cluster health (status, node + partition counts). Read-only.
fn bucket_list()
List buckets, enriched with usage/quotas/per-key permissions (factory: one
fn bucket_get(id?: string, globalAlias?: string, search?: string)
Get one bucket by exactly one of id, globalAlias or search (full detail). Read-only.
ArgumentTypeDescription
id?stringBucket id (exact)
globalAlias?stringGlobal alias to look up
search?stringPartial id/alias to search
fn key_list()
List access keys (id/name/expiry; factory: one `key` per key). Read-only.
fn key_get(id?: string, search?: string, showSecretKey?: boolean)
Get one access key by exactly one of id or search, with the buckets it can reach.
ArgumentTypeDescription
id?stringAccess key id (exact)
search?stringPartial id/name to search
showSecretKey?booleanInclude the secret access key in output (sensitive: stored in a vault, the data keeps a reference)
fn permissions_audit()
Build the full key×bucket permission matrix and risk flags (orphan keys,
fn bucket_create(globalAlias?: string, localAlias?: string, localAliasAccessKeyId?: string, localAliasRead?: boolean, localAliasWrite?: boolean, localAliasOwner?: boolean)
Create a bucket with a global (or local) alias. Idempotent on globalAlias:
ArgumentTypeDescription
globalAlias?stringGlobal alias for the new bucket (the usual case)
localAlias?stringLocal alias name (requires localAliasAccessKeyId)
localAliasAccessKeyId?stringAccess key the local alias belongs to
localAliasRead?booleanGrant the local alias's key read on the new bucket
localAliasWrite?booleanGrant the local alias's key write on the new bucket
localAliasOwner?booleanGrant the local alias's key owner on the new bucket
fn bucket_update(id: string, websiteEnabled?: boolean, indexDocument?: string, errorDocument?: string)
Update a bucket's quotas and/or static-website config (UpdateBucket).
ArgumentTypeDescription
idstringBucket id to update
websiteEnabled?booleanEnable/disable static website serving
indexDocument?stringWebsite index document key
errorDocument?stringWebsite error document key
fn bucket_delete(id: string, allowNonEmpty?: boolean)
Delete a bucket BY ID (verified to exist first; refuses a non-empty bucket
ArgumentTypeDescription
idstringBucket id to delete (verified to exist first)
allowNonEmpty?booleanAttempt deletion even if the bucket reports objects (Garage will still refuse a non-empty bucket)
fn bucket_alias_add(bucketId: string, globalAlias?: string, localAlias?: string, accessKeyId?: string)
Add a global or local alias to a bucket (AddBucketAlias). An alias
ArgumentTypeDescription
bucketIdstringBucket id
globalAlias?stringGlobal alias to add/remove
localAlias?stringLocal alias to add/remove
accessKeyId?stringAccess key the local alias belongs to (required for localAlias)
fn bucket_alias_remove(bucketId: string, globalAlias?: string, localAlias?: string, accessKeyId?: string)
Remove a global or local alias from a bucket (RemoveBucketAlias).
ArgumentTypeDescription
bucketIdstringBucket id
globalAlias?stringGlobal alias to add/remove
localAlias?stringLocal alias to add/remove
accessKeyId?stringAccess key the local alias belongs to (required for localAlias)
fn key_create(name?: string, allowCreateBucket?: boolean, expiration?: string, neverExpires?: boolean)
Create a new access key. The secret is returned on `key-result`
ArgumentTypeDescription
name?stringHuman-readable key name
allowCreateBucket?booleanPermit this key to create buckets
expiration?stringRFC 3339 expiry timestamp (omit + neverExpires=true for no expiry)
neverExpires?booleanKey never expires. false needs expiration: a new key has no expiry otherwise.
fn key_import(accessKeyId: string, secretAccessKey: string, name?: string)
Import a pre-existing access key pair (ImportKey) — e.g. to recreate a key
ArgumentTypeDescription
accessKeyIdstringExisting access key id to import
secretAccessKeystringMatching secret access key
name?stringHuman-readable key name
fn key_update(id: string, name?: string, allowCreateBucket?: boolean, expiration?: string, neverExpires?: boolean)
Update a key's name, create-bucket permission, and/or expiry (UpdateKey).
ArgumentTypeDescription
idstringAccess key id to update
name?stringNew name
allowCreateBucket?booleanSet/clear the create-bucket permission
expiration?stringNew RFC 3339 expiry
neverExpires?booleantrue clears the expiry. false does nothing; set expiration instead.
fn key_rotate(id: string, name?: string)
Rotate a key: create a NEW key, copy the OLD key's bucket grants and
ArgumentTypeDescription
idstringAccess key id to rotate (the OLD key)
name?stringName for the new key; defaults to the old key's name + ' (rotated)'
fn key_delete(id: string)
Delete an access key BY ID (verified to exist first). A key that is
ArgumentTypeDescription
idstringAccess key id to delete (verified to exist first)
fn key_allow(bucketId: string, accessKeyId: string, read?: boolean, write?: boolean, owner?: boolean)
Grant read/write/owner on a bucket to a key (AllowBucketKey). Idempotent.
ArgumentTypeDescription
bucketIdstringBucket id
accessKeyIdstringAccess key id
read?booleanRead permission
write?booleanWrite permission
owner?booleanOwner permission (manage aliases, quotas, website)
fn key_deny(bucketId: string, accessKeyId: string, read?: boolean, write?: boolean, owner?: boolean)
Revoke read/write/owner on a bucket from a key (DenyBucketKey). Each flag
ArgumentTypeDescription
bucketIdstringBucket id
accessKeyIdstringAccess key id
read?booleanRead permission
write?booleanWrite permission
owner?booleanOwner permission (manage aliases, quotas, website)
fn cluster_status()
Cluster status: this node's id, Garage version, layout version, and every
fn layout_get()
Get the current cluster layout — assigned roles plus any staged changes. Read-only.
fn layout_assign(nodeId: string, zone?: string, tags?: array, zoneRedundancy?: string)
STAGE a role for a node (zone, storage capacity in bytes or null for gateway,
ArgumentTypeDescription
nodeIdstringNode id to assign a role to (from cluster_status)
zone?stringZone/datacenter label for the node. Omit to keep the node's current zone
tags?arrayNode tags. Omit to keep the node's current tags (none for a node with no role yet).
zoneRedundancy?stringCluster zone redundancy: "maximum" or a positive integer (atLeast N). Omit to leave unchanged.
fn layout_apply()
Commit staged layout changes (ApplyClusterLayout). Defaults to the current
fn layout_revert()
Discard all staged (un-applied) layout changes (RevertClusterLayout).
fn cluster_init(nodeId?: string, zone?: string, tags?: array, zoneRedundancy?: string, force?: boolean)
First-boot convenience: assign a storage role to the node (defaults to the
ArgumentTypeDescription
nodeId?stringNode to configure; defaults to the responding node (correct for a single-node cluster)
zone?stringZone/datacenter label
tags?arrayOptional node tags
zoneRedundancy?string"maximum" or a positive integer (atLeast N); omit for the cluster default
force?booleanRe-initialise even if the layout already has assigned roles

Resources

cluster-health(1h)— Cluster health snapshot (status, node + partition counts)
bucket(infinite)— A bucket (aliases, usage, quotas, and per-key permissions)
key(infinite)— An access key (attributes + the buckets it can reach)
permission-audit(infinite)— Full key×bucket permission matrix plus risk flags
bucket-result(infinite)— Result of a bucket create/update/delete/alias operation
key-result(infinite)— Result of a key create/import/update/rotate/delete (may carry the secret, vaulted)
permission-result(infinite)— Result of a key allow/deny on a bucket
cluster-status(1h)— Cluster status (this node id, version, and all nodes/roles)
cluster-layout(1h)— Current cluster layout (assigned roles + staged changes)
layout-result(infinite)— Result of a layout stage/apply/revert or cluster_init
03Previous Versions1
2026.06.24.1
04Stats
A
93 / 100
Downloads
32
Archive size
35.9 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License1/2partial

    no SPDX license declared

  • Verified public repository2/2earned
05Platforms
06Labels