Getting Your Extension Used

You have built and packed an extension. Where it goes next depends on who should be able to use it:

Destination	Who sees it	Command
Local Designer	just you, on this machine	gtdx dev --once
The public store	anyone	gtdx login → gtdx publish --registry greentic-store
A tenant in Greentic Admin	one tenant’s users	gtdx component register

They are not steps in a sequence — pick the one that matches your intent.

Local Designer

The fastest loop, and what gtdx dev already does:

gtdx dev --once                                   # build + pack + install
gtdx install ./dist/my-ext-0.1.0.gtxpack -y       # or install an existing pack

Sign it, even locally. gtdx install accepts an unsigned pack without complaint, so this looks like it worked — but the Designer refuses to load one, and says so only in its own log:

failed to load extension greentic.my-ext-0.1.0:
signature verification failed: missing signature field

Installing and being loaded are separate things, and only the second one is what you wanted. Sign as part of packing:

gtdx keygen --out my-key.pem          # once
gtdx publish --sign --key my-key.pem  # writes a signed pack to dist/
gtdx install ./dist/my-ext-0.1.0.gtxpack -y

The Designer reads only ~/.greentic

It ignores GREENTIC_HOME and offers no flag to point it elsewhere. If you have been working in an isolated home, the Designer will not see anything you installed there — install into the default home when you want it to appear.

Current Designer builds need Postgres

Like Greentic Admin, the Designer now reads Postgres and will not finish starting without it:

GREENTIC_DESIGNER_DB_PG must be set to a postgres:// URL for the designer database

docker run -d --name gt-designer-pg \
  -e POSTGRES_USER=d -e POSTGRES_PASSWORD=d -e POSTGRES_DB=designer \
  -p 55433:5432 postgres:16-alpine

export GREENTIC_DESIGNER_DB_PG="postgres://d:d@127.0.0.1:55433/designer"

Extensions are loaded before this point, so you may see the load lines scroll past and then the process exit — the extension list in the log is still trustworthy.

If it still does not show up, the cause is almost always version skew rather than a bad pack. See Designer Compatibility and the troubleshooting section of the Extension Quickstart.

Once it loads, it appears in /api/extensions:

curl -s localhost:<port>/api/extensions | grep my-ext
# {"id":"greentic.my-ext","version":"0.1.0","kind":"design","enabled":true,"node_count":0}

The public store

Check the version slot first — reads are anonymous, so this needs no account and tells you immediately whether the version is free:

gtdx publish --verify-only --registry greentic-store
# verify-only: greentic.my-ext@0.1.0 slot free in https://store.greentic.cloud

Then authenticate and publish:

gtdx login                                        # browser device flow
gtdx publish --sign --key my-key.pem --registry greentic-store

gtdx login also takes --no-browser (prints the URL and code), --paste (paste a token by hand), and --token for CI. Publishing Extensions covers signing keys, trust policies, and how the store verifies a pack.

A tenant in Greentic Admin

gtdx component register registers a component that is already published as a component-tool for one tenant. It does not upload your extension — if you want the artifact distributed, publish it to the store first, then register its URL here.

1. Postgres. Current Admin builds read Postgres for at least one module, so SQLite alone is not enough despite what --db defaults to:

   docker run -d --name gt-admin-pg \
     -e POSTGRES_USER=admin -e POSTGRES_PASSWORD=admin -e POSTGRES_DB=greentic_admin \
     -p 55432:5432 postgres:16-alpine
   
   export GREENTIC_ADMIN_DB_PG="postgres://admin:admin@127.0.0.1:55432/greentic_admin"

   Without it, start-up fails with GREENTIC_ADMIN_DB_PG is not set.

2. Migrate and create an owner. reset-admin also needs the Postgres URL exported:

   greentic-admin migrate --db "sqlite://./admin.db?mode=rwc"
   greentic-admin reset-admin --db "sqlite://./admin.db?mode=rwc" \
     --email owner@local.test --password '<password>'

3. Start it.

   greentic-admin start --port 8090 --db "sqlite://./admin.db?mode=rwc"

4. Log in and keep the CSRF token. State-changing calls use a double-submit token returned in the login body — not as a cookie:

   curl -s -c jar.txt -o login.json -X POST localhost:8090/api/admin/login \
     -H 'Content-Type: application/json' \
     -d '{"email":"owner@local.test","password":"<password>"}'
   
   CSRF=$(python3 -c "import json;print(json.load(open('login.json'))['csrf_token'])")

5. Mint a service key. Owner-only, and the secret is returned exactly once:

   curl -s -b jar.txt -X POST localhost:8090/api/admin/service-keys \
     -H 'Content-Type: application/json' -H "x-csrf-token: $CSRF" \
     -d '{"label":"gtdx-local"}'
   # {"id":…,"prefix":"gts_…","label":"gtdx-local","key":"gts_…","created_at":…}

6. Create a tenant, if you do not have one. A fresh Admin has none, and registering against a missing tenant fails with a bare 404 not found:

   curl -s -b jar.txt -X POST localhost:8090/api/admin/tenants \
     -H 'Content-Type: application/json' -H "x-csrf-token: $CSRF" \
     -d '{"name":"Acme","slug":"acme"}'

7. Register the component.

   gtdx component register \
     --url "oci://ghcr.io/org/component-demo@sha256:<digest>" \
     --name demo-tool \
     --tenant acme \
     --user owner@local.test \
     --admin-url http://localhost:8090 \
     --admin-token gts_…
   # ✓ registered component-tool 'demo-tool' (id=…) url=… roles=(default)

   --admin-token also reads GREENTIC_ADMIN_TOKEN, or the greentic-admin key in ~/.greentic/credentials.toml. --user must be a tenant admin — it is sent as X-Greentic-User and the tenant slug as X-Greentic-Tenant.

Confirm it landed:

curl -s -H "Authorization: Bearer gts_…" \
     -H 'X-Greentic-Tenant: acme' -H 'X-Greentic-User: owner@local.test' \
     localhost:8090/api/v1/designer/tenant/me/component-tools

The binary may be older than its checkout

Both locally built Greentic binaries can be months behind the source beside them, and in each case the symptom points somewhere else entirely:

• greentic-admin — every API path returns the SPA’s HTML instead of JSON, so calls look like wrong URLs. If POST /api/admin/login answers with <!doctype html>, rebuild before debugging anything else.

• greentic-designer — a build predating the compat field rejects every v2 manifest with unknown field 'compat', which reads as a contract mismatch between gtdx and the Designer. It is not. Check what the binary actually contains:

  strings $(which greentic-designer) | grep -c min_designer_version
  # 0 means it predates the v2 contract, whatever --version says

--version does not tell you which contract or routes a binary implements, which is also why gtdx doctor’s Designer-compatibility check can report an extension as loadable while the Designer refuses it.

The admin binary was also renamed — greentic-designer-admin became greentic-admin. Older help text and command descriptions still use the old name.

Next

• Publishing Extensions — signing, trust policies, and store verification
• Designer Compatibility — why a built extension can be invisible
• Extension Quickstart — the whole path from install to publish