Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Connecting to Workflow Services

The fuzzball workflow connect command reaches a service running in a workflow. If the workflow declares a fuzzball.io/connect/<service-name> annotation for the service, the command runs a client program locally that connects to the service; otherwise it opens the service’s public endpoint in a web browser.

Connecting via the web UI

The web UI shows a Connect button for running workflows that expose a service endpoint. It appears in two places:

  • Workflow detail page – in the toolbar at the top of the page
  • Workflows list table – inline in each workflow row

The two locations behave differently while a workflow is starting up.

On the workflow detail page, the button appears once all of the following hold:

  1. The workflow has at least one named service endpoint defined
  2. The workflow is in a running state
  3. At least one of those endpoints belongs to a service that is currently running

The page polls the workflow’s status every ten seconds while any stage is pending or started, so the button becomes active shortly after the service starts. You do not need to reload the page.

In the workflows list table, the button appears only once it is ready to use.

The button links to the constructed endpoint URL but does not verify that the endpoint is actually reachable. “Running” here means the orchestrator has started the service container, not that the application inside it has finished booting, so the target service may still be starting up when the button becomes clickable.

On the workflow detail page, a workflow exposing a single endpoint gets a Connect button that opens it in a new browser tab. A workflow exposing several turns the button into a menu listing each one as service / endpoint; choosing one opens that endpoint in a new tab. Entries are ordinary links, so middle-click, modifier-click and “copy link address” work as anywhere else.

Endpoint selection

Only named endpoints belonging to a currently-running service are offered, ordered alphabetically by service name and, within a service, in the order its endpoints are declared. An endpoint whose service has not started yet is left out: it would answer 503.

The workflows list table has room for one link per row, so it offers the first endpoint in that same order. Use the workflow detail page, or the CLI fuzzball workflow connect command with the --name and --endpoint flags, to reach a specific one.

When to use the Web UI vs. CLI

The Connect button is ideal for quickly accessing web-based services such as Jupyter, RStudio, or other browser-accessible applications. For workflows that require client-script mode (see below), use the fuzzball workflow connect CLI command instead.

Connecting from the CLI

$ fuzzball workflow connect WORKFLOW_ID [flags] [-- COMMAND...]

Arguments:

ArgumentRequiredDescription
WORKFLOW_IDYesThe ID of a running workflow
COMMAND...NoArguments forwarded to the client program when the service is configured for client-script mode

Flags:

FlagDescription
--nameName of the service to connect to. If omitted and the workflow defines a single service, that service is selected automatically; otherwise the CLI prompts interactively.
--endpointName of the service endpoint to use. If omitted and the service defines a single endpoint, that endpoint is selected automatically; otherwise the CLI prompts interactively.

The command waits for the target service to report running – if the service declares a readiness-probe, until that probe passes – before opening the browser or launching the client program. While waiting, container logs for the service are streamed to the terminal.

Connection modes

fuzzball workflow connect supports two modes, selected automatically based on the workflow’s annotations:

Browser mode

If the service has no fuzzball.io/connect/<service-name> annotation declared on the workflow, the command resolves the URL of the selected endpoint and opens it in the default web browser. This is the simplest mode and is well suited to services that expose a web interface such as Jupyter or RStudio.

Client-script mode

If the workflow declares an annotation of the form fuzzball.io/connect/<service-name>, the CLI runs the annotation’s value as a command inside the service container and treats that command’s standard output as a client script. The CLI then writes the script to a temporary file on your own machine, makes it executable, and runs it, forwarding any arguments you supplied after -- on the fuzzball workflow connect command line.

This mode is useful when connecting to a service requires more than just a URL – for example, to fetch a generated access token or TLS configuration and then launch a local client with the right parameters.

Examples

Connect to the only service in a workflow (auto-select service and endpoint):

$ fuzzball workflow connect WORKFLOW_ID

Connect to a specific service by name:

$ fuzzball workflow connect --name jupyter WORKFLOW_ID

Select a specific endpoint within a service:

$ fuzzball workflow connect --name api-server --endpoint grpc WORKFLOW_ID

Forward arguments to a client script (client-script mode):

$ fuzzball workflow connect --name code-server WORKFLOW_ID -- --workspace /home/user/project

Connecting at workflow start

Both fuzzball workflow start and fuzzball workflow catalog start accept a --connect flag, which starts the workflow and then runs workflow connect against it as soon as it is ready.

$ fuzzball workflow start --connect my-workflow.fz
$ fuzzball workflow catalog start --connect <template>

When you pass --connect and the selected service has a fuzzball.io/connect/<service-name> annotation, the CLI prompts for arguments to pass to the client script.

Configuring a service for client-script mode

To enable client-script mode for a service, add a workflow-level annotation whose key is fuzzball.io/connect/<service-name> and whose value is the command to execute inside the service container. Services without this annotation always use browser mode.

  1. Declare the annotation fuzzball.io/connect/<service-name> on the workflow.
  2. Embed any helper files (template, substitution script, certificates, etc.) under the service’s files section so they are available inside the container.
  3. Have the annotation command print the final, ready-to-run client script to standard output. It must not depend on standard input, since the connect machinery does not forward a TTY to the in-container command.
  4. Use FB_* environment variables and any service-level env entries to inject runtime values into the generated script.

fuzzball.io/connect/<service-name> is the one fuzzball.io/ key you are expected to set yourself. The rest of that namespace is reserved for the platform, and the reservation is enforced on endpoint annotations rather than workflow-level ones.

Runtime variables available in the service container

When the connect command runs inside the service container, Fuzzball injects environment variables you can use to render runtime values into the generated client script. The most useful are:

VariableDescription
FB_WORKFLOW_IDID of the running workflow
FB_ACCOUNT_ID, FB_GROUP_IDID of the group (account) that owns the workflow – both carry the same value
FB_JOB_NAMEName of the service (matches the service key in the workflow)
FB_ENDPOINT_URLPublic URL of the first endpoint of the service (e.g. https://...)
FB_ENDPOINT_HOSTHostname portion of the first endpoint URL
FB_ENDPOINT_PATHPath portion of the first endpoint URL
FB_ENDPOINT_URL_<NAME>Public URL of the endpoint named <NAME>
FB_ENDPOINT_HOST_<NAME>Hostname portion of the endpoint named <NAME>
FB_ENDPOINT_PATH_<NAME>Path portion of the endpoint named <NAME>
FB_SERVICE_<SERVICE>_ENDPOINT_{URL,HOST,PATH,ID}_<NAME>The same for the endpoint named <NAME> of any service <SERVICE> in the workflow (see reaching another service’s endpoints)

<NAME> is the endpoint’s name uppercased, with every character that is not a letter, digit or underscore replaced by _. The openai-vllm endpoint in the example below therefore gets FB_ENDPOINT_URL_OPENAI_VLLM.

Any user-defined env entries declared on the service are also available to the connect command. Together with files embedded via the service’s files section, these variables are enough to generate a fully parameterized client script without baking values into the container image. See the Environment Variables Reference for the full list.

Example: vLLM server with a generated agent client

The example below defines a vLLM service that exposes an OpenAI-compatible API on a public HTTP endpoint and ships a connect command that emits a shell script to launch a local coding agent (opencode) wired up to the running model.

The service embeds two files:

  • /app/agent-script.tmpl – a template for the script that will run on your own machine, with placeholders such as __ENDPOINT_URL__ and __WORKFLOW_ID__.
  • /app/generate-agent-command.sh – the command named by the fuzzball.io/connect/vllm annotation. It runs inside the container, sed-substitutes the placeholders with values from the runtime environment (FB_ENDPOINT_URL, FB_WORKFLOW_ID, and the user-defined VLLM_API_KEY / VLLM_MODEL), and writes the finished script to standard output.
version: v4

volumes:
  data:
    use: ephemeral
    size: 5GB

annotations:
  fuzzball.io/connect/vllm: "sh /app/generate-agent-command.sh"

services:
  vllm:
    image:
      uri: docker://vllm/vllm-openai:latest
    persist: true
    network:
      ports:
        - name: openai-api
          port: 8000
          protocol: tcp
      endpoints:
        - name: openai-vllm
          port-name: openai-api
          protocol: http
          type: subdomain
          scope: public
    mounts:
      /home/vllm: data
    resource:
      cpu:
        cores: 8
      memory:
        size: 32GB
      devices:
        nvidia.com/gpu: 1
      annotations:
        nvidia.com/gpu.model: "H100"
    env:
      - HOME=/home/vllm
      - VLLM_API_KEY=replace-me
      - VLLM_MODEL=meta-llama/Llama-3.1-8B-Instruct
    script: |
      #!/bin/sh
      cd $HOME && exec vllm serve "$VLLM_MODEL" \
        --tensor-parallel-size 1 \
        --host 0.0.0.0 \
        --port 8000
    readiness-probe:
      tcp-socket:
        port: 8000
      initial-delay-seconds: 60
      period-seconds: 30
      failure-threshold: 60
      success-threshold: 1
    files:
      /app/agent-script.tmpl: |-
        #!/usr/bin/env bash
        if [ "$#" -ne 1 ]; then
          echo "project directory path is missing"
          exit 1
        fi
        mkdir -p /tmp/__WORKFLOW_ID__
        base64 -w0 <<EOF |
        {
          "\$schema": "https://opencode.ai/config.json",
          "model": "local/__MODEL__",
          "provider": {
            "local": {
              "npm": "@ai-sdk/openai-compatible",
              "name": "LocalAI (local)",
              "options": {
                "baseURL": "__ENDPOINT_URL__v1",
                "apiKey": "__API_KEY__",
                "headers": {
                  "keep_alive": -1
                }
              },
              "models": {
                "__MODEL__": {
                  "name": "__MODEL__",
                  "options": {
                    "max_tokens": 16000
                  }
                }
              }
            }
          }
        }
        EOF
        cat > /tmp/__WORKFLOW_ID__/agent.config
        docker run --rm -it \
          -v $1:/home/agent/workspace \
          --entrypoint /bin/bash \
          docker/sandbox-templates:opencode \
          -c "mkdir -p /home/agent/.config/opencode && \
              cat >/home/agent/.config/opencode/opencode.json \
              <(echo $(cat /tmp/__WORKFLOW_ID__/agent.config) | base64 -d) && \
              exec opencode"

      /app/generate-agent-command.sh: |-
        sed -e "s|__ENDPOINT_URL__|$FB_ENDPOINT_URL|g" \
            -e "s|__API_KEY__|$VLLM_API_KEY|g" \
            -e "s|__MODEL__|$VLLM_MODEL|g" \
            -e "s|__WORKFLOW_ID__|$FB_WORKFLOW_ID|g" \
            /app/agent-script.tmpl
scope: public puts this endpoint on the internet with no Fuzzball authentication – the only protection is vLLM’s own VLLM_API_KEY, which this example sets to the placeholder replace-me in plaintext. Set a strong value before running it, or use scope: group or scope: user and let Fuzzball authenticate callers. See Workflow Endpoints for endpoint scopes and tokens.

A user can then start the workflow and immediately drop into the local agent, passing the project directory as the only positional argument forwarded to the script:

$ fuzzball workflow start --connect vllm.fz
Enter arguments to pass to client script: /home/user/projects/myapp

Or, against an already-running workflow:

$ fuzzball workflow connect --name vllm WORKFLOW_ID -- /home/user/projects/myapp

In both cases Fuzzball:

  1. Waits for the vllm service readiness probe to pass.
  2. Runs sh /app/generate-agent-command.sh inside the vllm container.
  3. Captures the substituted script from standard output, writes it to a temporary file with executable permissions, and runs it locally with /home/user/projects/myapp as $1.

See also