Workflow Endpoints

When a workflow service exposes network endpoints (configured via the network section in your workflow definition), the fuzzball workflow endpoints command and its subcommands let you list the live endpoints you have access to, inspect a single endpoint, mint an access token for a non-public endpoint, or print the URL(s) derived from a workflow specification.

Listing live endpoints

fuzzball workflow endpoints list returns the workflow service endpoints currently alive on the cluster that you have access to. Access is scoped to the groups (accounts) you belong to and to your organization.

$ fuzzball workflow endpoints list

ENDPOINT ID         WORKFLOW ID   SERVICE     ENDPOINT   TYPE        SCOPE   URL
endpoint-1a2b3c4d    <workflow>    jupyter     web        path        user    https://endpoints.example.com/endpoints/...
endpoint-5e6f7a8b    <workflow>    api-server  grpc       subdomain   group   https://api-server.<workflow>.<account>.example.com/

Flags:

Use -o json or -o yaml for scripting; the structured output includes additional fields such as the owning account and organization.

$ fuzzball workflow endpoints list -o json

Showing a single endpoint

fuzzball workflow endpoints get shows the details of one endpoint by its ID, including its URL:

$ fuzzball workflow endpoints get ENDPOINT_ID

Generating an access token

Endpoints whose scope is not public require a bearer token. fuzzball workflow endpoints generate-token mints a token bound to the endpoint and carrying your identity:

$ fuzzball workflow endpoints generate-token ENDPOINT_ID

Present the returned token to the endpoint using the Authorization or FB-Authorization HTTP header.

The --expiration flag sets the token lifetime. It accepts the units understood by Go durations (s, m, h) plus day, week, month, and year units — 7d, 2w, 1mo, 1y (and long forms like 7days). When omitted, the server default lifetime is used:

# Valid for 24 hours
$ fuzzball workflow endpoints generate-token ENDPOINT_ID --expiration 24h

# Valid for 7 days
$ fuzzball workflow endpoints generate-token ENDPOINT_ID --expiration 7d

# Valid for 1 month
$ fuzzball workflow endpoints generate-token ENDPOINT_ID --expiration 1mo

Printing endpoint URLs from a workflow specification

Invoked with a workflow ID (and optional service and endpoint names), fuzzball workflow endpoints prints the endpoint URL(s) derived from that workflow's specification:

Accessing endpoints via the Web UI

In addition to querying endpoint URLs with the CLI, the Fuzzball Web UI provides a Connect button on workflow detail pages and in the workflows list. When a workflow is running and has at least one named endpoint defined, clicking the Connect button opens the workflow's primary endpoint in a new browser tab.

This provides a convenient shortcut for accessing web-based services without needing to copy and paste URLs. For details on how the primary endpoint is selected when multiple endpoints exist, and for information on connecting to specific non-primary endpoints or using client-script mode, see the Connecting to Workflow Services page.

$ fuzzball workflow endpoints WORKFLOW_ID [SERVICE_NAME] [ENDPOINT_NAME]

Arguments:

Get all endpoints for a workflow:

$ fuzzball workflow endpoints <workflow_id>

SERVICE       ENDPOINT   URL
jupyter       web        https://endpoints.example.com/endpoints/accounts/.../jupyter/web/
api-server    grpc       https://endpoints.example.com/endpoints/accounts/.../api-server/grpc/

Get all endpoints for a specific service, or a specific endpoint by name:

$ fuzzball workflow endpoints <workflow_id> jupyter
$ fuzzball workflow endpoints <workflow_id> jupyter web

Output the results as JSON (useful for scripting):

$ fuzzball workflow endpoints <workflow_id> -o json

Configuring endpoints in a workflow

Endpoints are declared in the network section of a service definition. For example, a Jupyter service that exposes a web endpoint:

services:
  jupyter:
    image:
      uri: docker://jupyter/base-notebook:latest
    script: |
      #!/bin/bash
      jupyter lab --ip=0.0.0.0 --no-browser
    resource:
      cpu:
        cores: 2
      memory:
        size: 4GB
    network:
      ports:
        - name: web
          port: 8888
          protocol: tcp
      endpoints:
        - name: web
          port-name: web
          protocol: https
          type: path
          scope: user

See the workflow syntax reference for full details on the network configuration options.

Environment variables for endpoints

When a workflow service runs, Fuzzball automatically injects environment variables for each configured endpoint. These variables allow your service code to discover the public URLs assigned to its endpoints.

For each endpoint, two environment variables are provided:

• FB_ENDPOINT_PATH_<ENDPOINT_NAME> — the full URL path to the endpoint
• FB_ENDPOINT_URL_<ENDPOINT_NAME> — the complete URL including protocol and host

Environment variable naming

The <ENDPOINT_NAME> suffix is derived from the endpoint's name field by:

1. Converting the name to uppercase
2. Replacing any character that is not a letter, digit, or underscore with an underscore (_)

This transformation ensures that the generated environment variable names are valid POSIX shell identifiers and compatible with all container runtimes.

Examples:

Using endpoint variables in startup scripts

You can reference these environment variables in your service's startup script to configure applications dynamically:

services:
  web-app:
    image:
      uri: docker://myapp:latest
    script: |
      #!/bin/bash
      echo "Service available at: $FB_ENDPOINT_URL_WEB"
      ./myapp --public-url="$FB_ENDPOINT_URL_WEB"
    network:
      ports:
        - name: http
          port: 8080
          protocol: tcp
      endpoints:
        - name: web
          port-name: http
          protocol: https
          type: path
          scope: user

For an endpoint named jupyter-notebook, you would reference the sanitized variable names:

echo "Notebook URL: $FB_ENDPOINT_URL_JUPYTER_NOTEBOOK"