Registry - Buttons

A registry is a catalog of installable packages. A package can be a button or a drawer. The registry answers: “What packages are available, what kind are they, what immutable versions exist, and what content hash should I install?” Registry installs use three different files:

.buttons/
  buttons.json          # desired dependencies; commit this
  buttons-lock.json     # exact resolved versions/hashes; commit this
  history.json          # local activity log; gitignored
	  buttons/
	    hello/
	      button.json       # runtime/package spec
	      main.sh
	      AGENTS.md
	  drawers/
	    deploy-pack/
	      drawer.json       # drawer/package spec
	      AGENTS.md

buttons.json is the project manifest. buttons-lock.json is the repeatable resolution. Installed button.json and drawer.json files stay focused on the local package spec; they do not store registry URLs, bearer keys, or the dependency source of truth.

Manifest

.buttons/buttons.json is user-authored desired state:

{
	  "schema_version": 1,
	  "dependencies": {
	    "@your-desk/hello": "latest",
	    "@your-desk/deploy-pack": "1"
	  }
	}

Dependency keys must be scoped package names in the form @desk/name. Names are unique per desk across buttons and drawers. The package kind is registry metadata, not part of the name.

Value	Meaning
`"latest"`	Floating dependency. `buttons update`, passive OTA, and publish-triggered OTA may move it to the latest published version.
`"1"`	Exact pin. Install resolves that immutable version; update/status may report newer versions as informational but must not mutate it.

Version ranges and per-dependency option objects are intentionally not part of the MVP.

Lockfile

.buttons/buttons-lock.json records the exact resolved set:

{
  "schema_version": 1,
  "dependencies": {
    "@your-desk/hello": {
      "kind": "button",
      "requested": "latest",
      "version": "1",
      "content_hash": "4f8c...",
      "installed_name": "hello",
      "resolved_at": "2026-07-01T12:00:00Z"
    }
  }
}

The lockfile is generated by buttons add, buttons install, and buttons update. It is committed for repeatable installs. It must never contain registry bearer keys or battery values.

button.json

Each installed button still has its own runtime spec:

{
  "schema_version": 1,
  "name": "hello",
  "version": "1",
  "description": "Say hello",
  "runtime": "shell",
  "args": [
    { "name": "name", "type": "string", "required": true }
  ],
  "env": {},
  "timeout_seconds": 60,
  "requires": {
    "@your-desk/base": "latest"
  },
  "requires_batteries": ["OPENAI_API_KEY"]
}

requires uses the same version policy as the root manifest: "latest" or an exact version. Transitive dependencies are resolved into the lockfile beside root dependencies.

drawer.json

Each installed drawer has its own workflow/package spec:

{
  "schema_version": 1,
  "name": "deploy-pack",
  "version": "1",
  "steps": [
    { "id": "build", "kind": "button", "button": "build" },
    { "id": "ship", "kind": "button", "button": "ship" }
  ]
}

Installing a drawer writes .buttons/drawers/<name>/drawer.json and installs every button referenced by its steps. Step button names are local names; package resolution uses the drawer’s desk namespace. For example, @your-desk/deploy-pack with step "button": "build" installs @your-desk/build.

Command Flow

Use the registry like a package manager:

buttons add @your-desk/hello
buttons add @your-desk/deploy-pack@1
buttons install
buttons status
buttons update

buttons add @desk/name writes .buttons/buttons.json with "latest" and installs immediately. The package can be a button or drawer.
buttons add @desk/name@1 writes an exact pin and installs that immutable version.
buttons install takes no package argument. It reads .buttons/buttons.json and honors .buttons/buttons-lock.json for repeatability.
buttons status reports available CLI and content updates.
buttons update updates the CLI and floating package dependencies only.

buttons install @desk/name is intentionally invalid. Use buttons add @desk/name to add a dependency.

Auth

Hosted-registry requests are bearer-authed (Authorization: Bearer <key>). Read and write use distinct batteries:

Operation	Battery	Press-time env override
`add`, `install`, `status`, `update`	`REGISTRY_KEY`	`$BUTTONS_BAT_REGISTRY_KEY`
`publish`	`REGISTRY_WRITE_KEY`	`$BUTTONS_BAT_REGISTRY_WRITE_KEY`

The registry base URL comes from $BUTTONS_REGISTRY_URL. This public repo does not bake in a real registry host. Bearer keys authorize what an operation may do; the workspace’s agent identity proves which device is acting. Enroll a device once with buttons agent setup before publishing to a hosted registry.

Publish Flow

buttons publish @desk/name publishes a local button or drawer folder to the configured registry:

BUTTONS_REGISTRY_URL=https://registry.example buttons publish @your-desk/hello
BUTTONS_REGISTRY_URL=https://registry.example buttons publish @your-desk/deploy-pack

The on-disk package is found by its bare local name (hello or deploy-pack), while @your-desk/name is the registry identity. Publish detects the package kind from button.json or drawer.json. Published versions are immutable. New buttons and drawers start at version 1; if that version already exists, publish bumps the local package spec to the next number and retries. Publishing a button bundles button.json, code files, and AGENTS.md. Publishing a drawer bundles drawer.json and AGENTS.md. Neither path uploads pressed/ run history or battery values.

Version Example

Publisher runs buttons create hello --code 'echo hello'.
Publisher runs buttons publish @your-desk/hello.
Agent workspace runs buttons add @your-desk/hello.
Agent lockfile resolves @your-desk/hello to version 1.
Publisher changes the source button and publishes again. Publish auto-bumps to version 2 if 1 already exists.
Agent workspace runs buttons status to see the available update.
Agent workspace runs buttons update to move the floating dependency to the new version.

If the agent had run buttons add @your-desk/hello@1, step 7 would leave it pinned at that exact version.

Hardening

A registry is treated as untrusted. Downloads are size-capped, tarball hashes are verified before extraction, file-content hashes are written to the lockfile, and extraction rejects absolute paths, traversal paths, macOS sidecar files, and run history. Before overwriting an installed package, update compares the current local files with the lockfile/install-state hash. Local edits are skipped, not overwritten.

HTTP Contract

A hosted registry implements:

GET /v1/meta — optional registry metadata, including minimum CLI version.
GET /v1/index — catalog entries { name, kind, version, tags, sha256 }, where kind is button or drawer and sha256 is the tarball hash. Latest is the last entry for a given name.
GET /v1/buttons/<@desk/name>/<version>/download — download the gzip tarball; should set X-Content-Sha256.
POST /v1/buttons/<@desk/name>/<version> — publish an immutable version with headers Content-Type: application/gzip, X-Content-Sha256, and X-Button-Kind.

​Manifest

​Lockfile

​button.json

​drawer.json

​Command Flow

​Auth

​Publish Flow

​Version Example

​Hardening

​HTTP Contract

​Related