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.
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:
- The workflow has at least one named service endpoint defined
- The workflow is in a running state
- 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.
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.
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.
$ fuzzball workflow connect WORKFLOW_ID [flags] [-- COMMAND...]Arguments:
| Argument | Required | Description |
|---|---|---|
WORKFLOW_ID | Yes | The ID of a running workflow |
COMMAND... | No | Arguments forwarded to the client program when the service is configured for client-script mode |
Flags:
| Flag | Description |
|---|---|
--name | Name 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. |
--endpoint | Name 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.
fuzzball workflow connect supports two modes, selected automatically based on the workflow’s
annotations:
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.
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.
Connect to the only service in a workflow (auto-select service and endpoint):
$ fuzzball workflow connect WORKFLOW_IDConnect to a specific service by name:
$ fuzzball workflow connect --name jupyter WORKFLOW_IDSelect a specific endpoint within a service:
$ fuzzball workflow connect --name api-server --endpoint grpc WORKFLOW_IDForward arguments to a client script (client-script mode):
$ fuzzball workflow connect --name code-server WORKFLOW_ID -- --workspace /home/user/projectBoth 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.
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.
- Declare the annotation
fuzzball.io/connect/<service-name>on the workflow. - Embed any helper files (template, substitution script, certificates, etc.) under the
service’s
filessection so they are available inside the container. - 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.
- Use
FB_*environment variables and any service-levelenventries 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.
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:
| Variable | Description |
|---|---|
FB_WORKFLOW_ID | ID of the running workflow |
FB_ACCOUNT_ID, FB_GROUP_ID | ID of the group (account) that owns the workflow – both carry the same value |
FB_JOB_NAME | Name of the service (matches the service key in the workflow) |
FB_ENDPOINT_URL | Public URL of the first endpoint of the service (e.g. https://...) |
FB_ENDPOINT_HOST | Hostname portion of the first endpoint URL |
FB_ENDPOINT_PATH | Path 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.
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 thefuzzball.io/connect/vllmannotation. It runs inside the container,sed-substitutes the placeholders with values from the runtime environment (FB_ENDPOINT_URL,FB_WORKFLOW_ID, and the user-definedVLLM_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: publicputs this endpoint on the internet with no Fuzzball authentication – the only protection is vLLM’s ownVLLM_API_KEY, which this example sets to the placeholderreplace-mein plaintext. Set a strong value before running it, or usescope: grouporscope: userand 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/myappOr, against an already-running workflow:
$ fuzzball workflow connect --name vllm WORKFLOW_ID -- /home/user/projects/myappIn both cases Fuzzball:
- Waits for the
vllmservice readiness probe to pass. - Runs
sh /app/generate-agent-command.shinside thevllmcontainer. - Captures the substituted script from standard output, writes it to a temporary file with
executable permissions, and runs it locally with
/home/user/projects/myappas$1.
- Workflow syntax reference: services
for the full set of
servicesandnetworkconfiguration options. - Workflow Endpoints for how endpoint URLs are constructed, and for endpoint scopes and access tokens.
- Serving an AI Model for starting a model from the workflow catalog rather than writing the service yourself.
- Using OpenCode with a Fuzzball-Hosted Model for the identity-authenticated alternative to the example above.