> ## Documentation Index
> Fetch the complete documentation index at: https://docs.servflow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up Your Local Environment

> Download and configure ServFlow Pro for local development

ServFlow Pro is a visual backend engine for building and running APIs. This guide walks you through setting up ServFlow Pro on your local machine for development. By the end, you'll have a fully functional local environment ready to build and test APIs.

<Tip>
  ServFlow Pro runs in two modes: **Dashboard Mode** (with `--dashboard`) for visual development, and **Headless Mode** (without `--dashboard`) for running YAML configurations directly. This guide focuses on Dashboard Mode for local development. See [Running Modes](/running-modes) to learn more.
</Tip>

## Prerequisites

* **Docker** (recommended) or a downloaded ServFlow Pro binary
* A terminal or command-line interface

## Download Options

### Using Docker (Recommended)

Pull the official ServFlow Pro Docker image:

```bash theme={null}
docker pull servflow/servflow-pro
```

### Using the Binary

Download pre-built binaries from the [Releases](https://github.com/Servflow/servflow-pro/releases) page.

Available platforms:

* **Linux** (x86\_64, arm64)
* **macOS** (x86\_64, arm64)

```bash theme={null}
# Download and extract (example for Linux x86_64)
tar -xzf servflow-pro_Linux_x86_64.tar.gz

# Make executable
chmod +x servflow-pro
```

## Configuration Setup

ServFlow Pro uses a TOML configuration file. Create a `config.toml` file in your working directory:

```toml theme={null}
[server]
port = "8080"
config_folder = "./configs"
env = "development"

[sqlite]
path = "./data/servflow.db"
master_key = "your-local-dev-master-key"
```

Next, create the configs directory where your API configurations will be stored:

```bash theme={null}
mkdir configs
```

<Tip>
  The `config_folder` is the only required configuration. ServFlow will use sensible defaults for everything else.
</Tip>

## Port Configuration

ServFlow Pro runs two servers:

| Server     | Default Port | Purpose                               |
| ---------- | ------------ | ------------------------------------- |
| API Server | `8080`       | Handles incoming API requests         |
| Dashboard  | `3000`       | Web UI for building and managing APIs |

### Customizing Ports

You can change ports in your `config.toml`:

```toml theme={null}
[server]
port = "9000"
```

Or use an environment variable:

```bash theme={null}
export SERVFLOW_SERVER_PORT=9000
```

One port serves the engine, the API, and the dashboard, so changing it moves all three.

<Note>
  Environment variables take precedence over values in the TOML file.
</Note>

## Master Key for Secrets

The `master_key` encrypts secrets stored by ServFlow, such as API keys and credentials.

```toml theme={null}
[sqlite]
master_key = "your-secure-master-key"
```

Or set it via environment variable:

```bash theme={null}
export SERVFLOW_SQLITE_MASTER_KEY=your-secure-master-key
```

<Warning>
  **Security Best Practices:**

  * Use a strong, unique key (at least 32 characters recommended)
  * Never commit your master key to version control
  * Use environment variables in production environments
  * If you change the master key, previously encrypted secrets cannot be decrypted
</Warning>

If no master key is set, secrets management will be disabled in the dashboard.

## Optional: SQLite Storage

SQLite provides persistent storage for additional features. When configured, it enables:

* **Secrets Management** — Encrypted storage for API keys and credentials
* **OAuth Integrations** — OAuth provider configurations and token storage
* **Metrics Storage** — Usage and performance metrics persistence

To enable SQLite, add the following to your `config.toml`:

```toml theme={null}
[sqlite]
path = "./data/servflow.db"
```

Make sure to create the data directory:

```bash theme={null}
mkdir data
```

<Note>
  If SQLite is not configured, ServFlow falls back to file-based storage. This is fine for basic local development but limits available features.
</Note>

## Optional: Tracing with OpenTelemetry

ServFlow Pro supports distributed tracing via OpenTelemetry, which helps you debug and monitor API workflows.

### Setting Up a Local Collector

You can run Jaeger locally as a tracing collector:

```bash theme={null}
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest
```

This starts Jaeger with:

* **Port 16686** — Jaeger UI for viewing traces
* **Port 4318** — OTLP HTTP collector endpoint

### Configuring Tracing

Add the tracing configuration to your `config.toml`:

```toml theme={null}
[tracing]
enabled = true
service_name = "servflow-local"
collector_endpoint = "http://localhost:4318"
```

Or use environment variables:

```bash theme={null}
export SERVFLOW_TRACING_ENABLED=true
export SERVFLOW_TRACING_SERVICE_NAME=servflow-local
export SERVFLOW_TRACING_COLLECTOR_ENDPOINT=http://localhost:4318
```

Once configured, you can view traces at `http://localhost:16686`.

## Running ServFlow Pro

### With Docker

```bash theme={null}
docker run -d \
  --name servflow-pro \
  -p 8080:8080 \
  -p 3000:3000 \
  -v $(pwd)/config.toml:/app/config.toml \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/configs:/app/configs \
  servflow/servflow-pro start --config /app/config.toml --dashboard
```

### With the Binary

```bash theme={null}
./servflow-pro start --config config.toml --dashboard
```

### Command Line Options

| Flag               | Description                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| `--config, -c`     | Path to TOML configuration file (required)                               |
| `--dashboard`      | Start the web dashboard interface                                        |
| `--import-configs` | Import API configs from config folder to SQLite (requires `--dashboard`) |

## Verifying Your Setup

### Test the API Server

```bash theme={null}
curl http://localhost:8080/health
```

You should receive a response indicating the server is running.

### Access the Dashboard

Open your browser and navigate to:

```
http://localhost:8080/dashboard
```

The dashboard is served under `/dashboard` on the same port as the engine. On a fresh instance you'll be asked to complete setup and create an account before the builder appears — see [First run](/installation#first-run-create-your-account).

<Check>
  **You're all set!** Your local ServFlow Pro environment is configured and running.
</Check>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Your First API" icon="rocket" href="/quickstart">
    Follow the quickstart guide to build a Hello World API in under 5 minutes.
  </Card>

  <Card title="Configuration Reference" icon="gear" href="/references/configuration">
    Explore all configuration options and environment variables.
  </Card>
</CardGroup>