Self-host ServFlow

Install ServFlow on your own machine with Docker, the binary, or npm, and create the first account

This guide installs ServFlow on a machine you manage and gets you signed in to its dashboard. Self-host when you want your data on your own machine, or when your agents need to reach services on a private network. If you just want to use ServFlow, sign up at dash.servflow.io instead and follow Your first agent.

​

Before you begin

• 100 MB of free RAM. ServFlow is a single Go binary with an embedded dashboard.
• A supported platform: Linux or macOS on x86_64 or arm64, or any host that runs Docker.
• Outbound network access to the LLM providers your agents use.

​

Get a working configuration

ServFlow reads a TOML configuration file. You do not need to write one. The first time you run servflowai start without a --config flag, it writes a complete default configuration to ~/.servflow/config.toml and starts with it. The database lands in ~/.servflow/data/ and the server listens on port 8080.

To see the configuration an instance is using, run:

servflowai resource settings view

The Docker image seeds its own configuration into /data on first boot, so the same applies there. For what each key means, see the Configuration reference.

​

Install with Docker

1. Start the container with the port published and a volume mounted at /data:

   docker run -d \
     --name servflowai \
     -p 8080:8080 \
     -v servflowai-data:/data \
     servflow/servflowai:latest
   

   The image starts the server with the dashboard enabled. The volume holds the configuration file and the database, so keep it across upgrades.

2. Open http://localhost:8080/dashboard/. The first-run setup screen appears.

​

Install the binary

1. Download the archive for your platform from the Releases page. Archives are named by platform, for example servflowai_Linux_x86_64.tar.gz or servflowai_Darwin_arm64.tar.gz.

2. Extract it and move the binary onto your PATH:

   tar -xzf servflowai_Linux_x86_64.tar.gz
   sudo mv servflowai /usr/local/bin/
   

3. Start the server with the dashboard enabled:

   servflowai start --dashboard
   

   The log prints servflowai started.

4. Open http://localhost:8080/dashboard/. The first-run setup screen appears.

​

Install with npm

The npm package downloads the same binary for your platform. It supports macOS and Linux on x86_64 and arm64.

1. Install the package globally:

   npm install -g servflowai
   

2. Start the server with the dashboard enabled:

   servflowai start --dashboard
   

   The log prints servflowai started.

3. Open http://localhost:8080/dashboard/. The first-run setup screen appears.

​

Create the first account

The dashboard requires an account. On a fresh instance the setup and registration screens are open until the first account exists, then they close.

1. Set up your instance

   Choose a workspace directory and whether to enable tracing. Optional: paste a ServFlow authentication token to connect the instance to servflow.io for trace export and AI assist. Your answers are written to the configuration file.

2. Create your account

   Enter an email address and a password of at least 8 characters. This creates the first account. Creating further accounts requires being signed in.

3. Restart the server

   Stop the running process and start it again. The settings from step 1 are read when the server starts. With Docker, run docker restart servflowai.

4. Sign in

   Open the dashboard again and sign in with your credentials. The dashboard opens on the agents page.

To run without the account gate on a trusted local machine, set mode = "none" under [authentication] in the configuration file.

​

Verify

From the terminal, list the agents in the store. On a fresh instance the list is empty and the command exits without error:

servflowai resource agent list

If you use Docker, run it inside the container:

docker exec servflowai servflowai resource agent list --config /data/config.toml

​

Run it properly

For an instance that outlives a first try:

• Encrypt secrets at rest. Set master_key under [sqlite], and set it through the SERVFLOW_SQLITE_MASTER_KEY environment variable rather than the file. See Secrets.
• Back up the database. The file set by path under [sqlite] holds your agents, integrations, secrets, and accounts.
• Do not expose the server directly. Put it behind a reverse proxy with TLS.
• Run it as a service. Use a Docker restart policy, or a systemd unit for the binary, so it comes back after a reboot.
• Pin a version. Use a tagged image or package version rather than latest.

​

Related

Create an agent

Build an agent in the dashboard or from a config file, and call it over HTTP.

Configuration reference

Every TOML key and environment variable.