Run an AgentApp with a local SuperLink

Run an AgentApp locally with Flower’s Community Edition runtime. This setup is useful while developing an app: it runs SuperLink and the AgentApp processes on your machine, without a SuperGrid account or Enterprise services.

Run the CLI and SuperLink from the same project environment to avoid protocol mismatches.

If you haven’t created an AgentApp yet, start with Write your first AgentApp.

Warning

This guide disables TLS and is intended for local development only. Do not expose the insecure SuperLink ports to an untrusted network.

Configure a model provider

The local runtime needs an Open Responses-compatible model endpoint. Set the provider configuration in the terminal where you’ll start SuperLink.

To use Flower’s default model endpoint, provide a Flower API key:

$ export FLWR_MODEL_API_KEY="<your-api-key>"

To use another Open Responses-compatible endpoint, set its full /responses URL instead:

$ export FLWR_MODEL_API_ENDPOINT="http://127.0.0.1:8080/v1/responses"
$ export FLWR_MODEL_API_KEY="<your-provider-api-key>"

You can omit FLWR_MODEL_API_KEY when the custom endpoint does not require authentication. The model and AgentApp subprocesses inherit these variables from SuperLink.

Account connectors configured in SuperGrid are not available to this local unauthenticated runtime. Built-in connectors depend on the local runtime and provider configuration.

Start SuperLink

From your AgentApp project directory, start an insecure local SuperLink:

$ uv run flower-superlink --insecure

SuperLink starts its HTTP API on 127.0.0.1:8000 and launches the local processes needed to execute the AgentApp and its model requests. You don’t need to start a SuperNode for an AgentApp run.

Leave this terminal open while you run the app.

Add a local connection

In another terminal, add a connection for the local Control API to ~/.flwr/config.toml:

[superlink.local-agent]
address = "127.0.0.1:8000"
insecure = true

The connection name is local-agent. It doesn’t require flwr login because the local SuperLink has no account authentication configured.

Chat with the AgentApp

From the AgentApp project directory, select the local connection and start Flower Chat:

$ export FLWR_CHAT_SUPERLINK=local-agent
$ uv run flwr chat

Tip

To load the app and start chatting, see Load and chat with the AgentApp.

Inspect and stop the run

Press Ctrl+C during a Flower Chat response to stop that run. For a known run ID, inspect or stop it from the CLI:

$ uv run flwr list --run-id <run-id> local-agent
$ uv run flwr log <run-id> local-agent --show
$ uv run flwr stop <run-id> local-agent

Press Ctrl+C in the SuperLink terminal when you’re finished.

Troubleshoot the local runtime

Common problems include:

• Model API key is not set: export FLWR_MODEL_API_KEY in the SuperLink terminal, then restart SuperLink

• Invalid model endpoint: FLWR_MODEL_API_ENDPOINT must include the full /responses path

• Connection refused: confirm that SuperLink is still running and that the configured address is 127.0.0.1:8000

• Version mismatch: start SuperLink and run the CLI from the same project environment so they use compatible Flower versions