Install a package

Installs a package from a registry reference or a local path. The response is 202 with an install job, because a package carrying Go code triggers a rebuild and binary swap; poll the job (or watch events) for progress. Resource-only packages complete near-instantly. Conflicts — two packages claiming one slot — surface asynchronously, on the failed job’s error envelope, as NRY-0006 naming both claimants (enable/disable are the one synchronous exception: they report a slot conflict as a direct 409 instead, since they have no job to poll). A failed build never leaves the user without a working agent: the previous binary stays in place (NRY-0007). A hosted home refuses it 422: a package is compiled and run on the host’s own machine, and an extension registered at an HTTPS address is the hosted way.

POST /v1/packages

Install a package

cURL

curl --request POST \
  --url https://api.example.com/v1/packages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source": "registry.lerian.studio/review-pack",
  "trustAcknowledged": true
}
'

202

{
  "id": "5c3d1e9f-7a8b-4c2d-0e4f-6a8b0c2d4e6f",
  "packageName": "lerian/review-pack",
  "source": "registry.lerian.studio/review-pack",
  "status": "building",
  "startedAt": "2026-08-08T12:40:00.000Z"
}

Authorizations

Authorization · string · header · required

Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.

Body

application/json

Request to install a package.

source · string · required

A registry reference or a local directory path.

Maximum string length: 1024

trustAcknowledged · boolean · default: false

Must be true when source carries compiled Go code: installing it means trusting it fully — it runs in the host's own process, with no sandbox. Omitted or false on a code-carrying source is rejected (422) naming the acknowledgement, before any install is attempted.

Response

202

application/json

Install job started. Poll it for progress.

An asynchronous package operation. Code-carrying packages resolve, build and swap the binary; a failure at any stage leaves the previous binary intact and serving — the user is never left without a working agent.

id · string<uuid> · required

status · enum<string> · required

Available options: resolving, building, swapping, done, failed

startedAt · string<date-time> · required

packageName · string

Maximum string length: 256

source · string

Maximum string length: 1024

error · object

Present when status is failed; the previous binary is intact.

Show child attributes

Example:

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

finishedAt · string<date-time>