Running ServFlow

What a ServFlow instance serves, how the dashboard and engine share one port, and how storage and authentication shape a deployment

ServFlow is an agent builder: you define AI agents and the workflows they run, and a Go engine serves them. This page explains what a running instance actually is — what it serves, on which paths, and which choices change its behaviour.

It is a conceptual overview. For step-by-step instructions, follow the links at the end.

One process, one port

A ServFlow instance is a single process listening on one port (server.port, default 8080).

The workflow engine owns the root path. A workflow whose entry listens on /hello answers at http://localhost:8080/hello — there is no prefix. Everything else is mounted alongside it:

Path	What it serves	When
/<listen path>	Your workflows and agent webhooks	Always
/dashboard	The visual builder UI	With --dashboard
/api/...	The management API the dashboard uses	With --dashboard

Earlier versions ran the dashboard as a second server on its own port. They no longer do — one port serves everything, and the dashboard is a path on it.

With or without the dashboard

The --dashboard flag is the main deployment choice. It changes what is mounted, not how workflows execute — an agent behaves identically either way.

With the dashboard

servflow-pro start --config config.toml --dashboard

Mounts the visual builder and the management API. This is the mode for building: creating agents, wiring workflows, managing secrets and integrations, and debugging visually.

Without the dashboard (headless)

servflow-pro start --config config.toml

Serves only your workflows. Nothing else is exposed, which makes it the usual choice for production: a smaller surface, no UI assets, and no management API reachable from outside.

Headless instances are not read-only — the CLI still manages resources by talking to the store directly, and can signal a running instance to hot-reload.

Comparison

	With --dashboard	Headless
Serves workflows and agents	✅	✅
Visual builder	✅	❌
Management API	✅	❌
Managed by the CLI	✅	✅
Typical use	Building, debugging	Production, containers

Where configuration lives

Agents, workflow configs, secrets, and user accounts live in SQLite (sqlite.path). This is what the dashboard reads and writes, and what the CLI operates on.

The server.config_folder directory holds workflow configuration files on disk. An instance can serve configs from files, from the store, or both — and --import-configs performs a one-time import of files into SQLite so they become editable in the dashboard.

Without SQLite, ServFlow falls back to file-based storage. Secrets management, OAuth integrations, and user accounts are unavailable in that mode.

How access is gated

A dashboard-enabled instance is gated by default: authentication.mode = "local" requires a username and password, with the first account bootstrapping the instance.

Setting mode = "none" removes the gate entirely. Because the management API sits behind the same gate, an open instance should never be reachable from an untrusted network.

Headless instances expose no management API, so this setting matters most when the dashboard is enabled.

A typical lifecycle

Most teams move from visual building to a reproducible deploy:

1. Build with the dashboard, creating agents and workflows interactively
2. Export or author the resulting configs as JSON/YAML and commit them
3. Deploy headless, with configuration supplied by environment variables
4. Update by changing configs in version control and letting CI apply them

Because the dashboard and the CLI operate on the same objects, no translation step is needed between stages.

Next steps

Deploy with the dashboard

Walk through building an agent and its first endpoint visually.

Deploy declaratively

Define a workflow as a config file and deploy it from the CLI.

Configuration Reference

Every TOML option and environment variable.

Agents

The object model an instance serves.