Your first transfer.
Download one binary, create an admin, and connect with the client you already use.
1. Get Kervan
Download the v0.9.0 release archive for Linux, macOS or Windows from GitHub Releases, verify it against checksums.txt, and extract it into a working directory. The release binary includes the management WebUI. You do not need Go, Node.js or an external database to run it.
The examples below use a Unix shell. On Windows, run .\kervan.exe instead of ./kervan. Keep the working directory consistent: the default kervan.yaml and ./data paths are relative to it.
# Check the extracted binary
./kervan version
# Generate kervan.yaml in the current directory
./kervan init
2. Create your first admin
Create an administrator before you start the server. Choose a strong, unique password; the value below is an example to replace. The default configuration does not ship with an admin password.
./kervan admin create \
--username admin \
--password 'Choose-a-unique-password!'
# Validate your configuration
./kervan check
# Start the server
./kervan
Review listener exposure and firewall rules before making the server reachable. FTP is unencrypted; use SFTP or configure FTPS for sensitive transfers. Enable TLS for a remotely accessible WebUI.
3. Make a connection
Open http://localhost:8080 to sign in to the embedded WebUI. Create a regular transfer user with its own home directory and permissions. The CLI can also create users while the server is running.
# In a second terminal, from the same working directory
./kervan user create \
--username alice \
--password 'Another-unique-password!' \
--home-dir /uploads
# Connect, verify the server host key, and enter Alice’s password
sftp -P 2222 alice@localhost
Keep administration and file transfer accounts separate. In SFTP, use put report.csv to upload and ls to list files.
Default listeners
SFTP and SCP share one SSH listener. Explicit FTPS shares the FTP listener; the optional implicit TLS listener uses its own port.
| Service | Port | Default behavior |
|---|---|---|
| FTP | 2121 | Enabled; passive ports 50000–50100 |
| FTPS | 2121 / 990 | Disabled; certificate and key required |
| SFTP / SCP | 2222 | Enabled; Ed25519 host key generated |
| WebUI / API / metrics | 8080 | Enabled; create an admin before startup |
| Debug / pprof | 6060 | Disabled; localhost binding when enabled |
Configuration that stays readable
Kervan reads kervan.yaml by default. Pass -config for a different file. YAML values can be overridden with KERVAN_<SECTION>__<KEY> environment variables, with double underscores between nested levels.
# Use a specific config file
./kervan -config /etc/kervan/kervan.yaml
# Example environment override (Unix shell)
KERVAN_FTP__PORT=2221 ./kervan
Selected WebUI, security and bandwidth settings can reload at runtime. Listener and storage changes can require a restart; the reload API reports applied_paths and restart_paths.
Build from source
Source builds require Go 1.26.1 or newer; the repository pins Go 1.26.9. Building the embedded WebUI also requires Node.js and npm. Run the repository’s build helper before compiling the server.
git clone https://github.com/KervanServer/kervan.git
cd kervan
go run ./scripts
go build -o kervan ./cmd/kervan
./kervan init
Found something to improve? Open a website issue