Skip to content

Share a deployment#

A share lets another workspace use one of your deployments without its own GPUs: call it through the gateway with an API key, try it in its Playground, or both. Answers come from your machines; you keep control and can revoke at any time. Use it for a central model team serving other teams, or to give a partner organisation access to a model you host.

Before you begin#

  • The editor or admin role in the workspace that owns the deployment.
  • The other workspace's organisation and workspace short names, as in its console address (/o/<org>/w/<workspace>).
  • For the API examples, ASTRAEUS_TOKEN, CONSOLE and API as in Add a model.

Share it#

  1. Open the deployment's page. Under Sharing, press Share.
  2. Choose A workspace (and give its Organisation and Workspace), or A namespace of this cluster.
  3. They may: call with an API key, try in their Playground, or both.
  4. Optional: Expires after (days) and a Note (They see it.).
  5. Press Share. The share is listed with its state, access and expiry.

Find the other workspace's namespace on its cluster:

$ curl -fsS "$CONSOLE/share-targets?org=partner&workspace=research" -H "Authorization: Bearer $ASTRAEUS_TOKEN"
{"org":"partner","org_name":"Partner Labs","workspace":"research","workspace_name":"Research","namespace":"ws-5c1e…"}

Then create the share in your workspace:

$ curl -fsS -X POST "$API/deployment-shares" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    -H 'content-type: application/json' -d '{
      "metadata": {"name": "for-partner"},
      "spec": {
        "deployment": "chat",
        "to": {"org": "partner", "workspace": "research", "namespace": "ws-5c1e…"},
        "access": ["call", "playground"],
        "expires_at": "2026-12-31T00:00:00Z",
        "note": "Q4 pilot"
      }
    }'
Field Description
metadata.name The share's name: lowercase letters, digits and -, at most 63 characters.
spec.deployment One of your workspace's deployments.
spec.to {org, workspace, namespace} of another workspace; or spec.to_namespace, another namespace of the same cluster. Not both, and not your own workspace.
spec.access At least one of call and playground.
spec.expires_at Optional; a time in the future.
spec.note Optional; at most 500 characters; they see it.

GET $API/deployment-shares?deployment=chat lists a deployment's shares. Each is Active or Revoked.

Give them a key#

With call access, the other workspace calls the deployment with an API key. Either:

  • You make a key for them: on the share's row press Create a key for them. It is a key of your workspace that may call this deployment only. Hand it over; revoke it on your API keys page when you are done.
  • They make their own: in their console, API keys → New key, tick Also deployments shared with this workspace and the deployment. With the API, they list it in spec.shared_deployments as <your namespace>.<deployment>.

With their own key, they put <your namespace>.<deployment> in model, and call the gateway of your cluster. GET /v1/models with their key lists it with that id.

What they see#

On their Deployments page, under Shared with this workspace: the deployment, shared by your workspace, the model name to use, what they may do, the expiry, and a Playground button. In their Playground it appears under Shared with this workspace. They never see your machines, replicas or engine arguments.

Their tokens are counted under your deployment, and in their workspace's usage as shared:<your namespace>.<model>.

Revoke a share#

On the deployment's page, press Revoke on the share's row. Their calls are refused within half a minute; keys you made for them stay until you revoke them on the API keys page. Remove deletes a share that is no longer active.

$ curl -fsS -X POST "$API/deployment-shares/for-partner/revoke" -H "Authorization: Bearer $ASTRAEUS_TOKEN"
$ curl -fsS -X DELETE "$API/deployment-shares/for-partner" -H "Authorization: Bearer $ASTRAEUS_TOKEN"

Deleting the deployment deletes its shares.

Troubleshooting#

Symptom Cause Fix
403 model_not_shared on their call The share was revoked, has expired, or does not grant call. Share again with call with an API key.
404 model_not_found on their call Their key does not list the shared deployment, or they used the bare name. Add it to the key's shared deployments; use <namespace>.<deployment> in model.
400: a workspace other than the owner's You tried to share with your own workspace. Its members already use the deployment directly.
This cluster does not share deployments yet on the deployment's page The cluster's version predates sharing. Make an API key limited to the deployment and hand it over.