First Run

🔗Starting Hugin

Run hugin with no arguments to launch the desktop GUI:

hugin

The proxy starts automatically on 127.0.0.1:8080 and the API server on 127.0.0.1:8081. On first run, Hugin generates a CA certificate and creates an empty project database.

🔗CLI Mode

If you prefer to run Hugin without the GUI (headless servers, SSH sessions, CI pipelines):

# Start proxy + API in the foreground
hugin start

# Custom ports
hugin start --port 9090 --api-port 9091

# Bind to a different interface
hugin start --bind 0.0.0.0

# Start with the embedded MCP server (Claude Code / Claude Desktop)
hugin start --mcp

# Verbose logging (global flag — works on any subcommand)
hugin -v start

Press Ctrl+C to stop.

🔗Headless Server Mode

For remote or team access, use serve which binds to 0.0.0.0 by default and requires token authentication:

hugin serve

# Disable token auth (only on trusted networks)
hugin serve --no-auth

Create access tokens with hugin token create --label <name>. List with hugin token list. Revoke with hugin token revoke <hgn_…>.

🔗Force-Headless Mode

To launch without the GUI even when running from a desktop session:

hugin --headless

🔗CLI Command Overview

Command	Purpose
`hugin`	Launch desktop GUI
`hugin start`	Run proxy + API in foreground
`hugin serve`	Headless server with token auth (binds 0.0.0.0)
`hugin status`	Show running proxy status
`hugin doctor`	System health + security diagnostics
`hugin setup [--headless]`	First-run setup wizard
`hugin init`	Generate default `config.toml`
`hugin config show`	Print resolved configuration
`hugin config telemetry on\|off`	Toggle anonymous telemetry
`hugin ca export [--output PATH] [--print]`	Export CA certificate
`hugin ca trust`	Install CA into the system trust store (requires sudo)
`hugin ca untrust`	Remove CA from the system trust store (requires sudo)
`hugin browse <url>`	Open URL in Hugin’s Chrome-fingerprinted visual browser
`hugin flows / hugin flow <id>`	List or inspect captured flows
`hugin scanner …`	Manage Synaps WASM modules (update/install/remove/list)
`hugin plugin …`	Manage Lua plugins and dynamic MCP plugins
`hugin token …`	Manage access tokens for `serve` mode
`hugin account …`	Manage Pro license activation
`hugin update [--check]`	Check for updates or update in-place
`hugin verify <file>`	Verify Ed25519 signature of a downloaded artifact
`hugin oastify-setup --domain D --ip I`	Generate self-hosted Oastify deployment guide
`hugin mcp`	Run the embedded MCP server on stdio (Claude integration)

Global flags (work with any subcommand):

-v, --verbose — debug-level tracing
--headless — force GUI-less mode

🔗Setup Wizard

On first launch, Hugin runs a setup wizard that walks through proxy port selection, CA certificate installation, and optional Pro license activation. You can re-run it any time:

hugin setup

For non-interactive environments:

hugin setup --headless

🔗Data Directory

All Hugin data lives under ~/.hugin/:

~/.hugin/
  config.toml              Configuration file
  Hugin-Proxy-CA.pem       CA certificate (install in your browser/OS)
  Hugin-Proxy-CA-key.pem   CA private key (keep private)
  hugin.db                 SQLite database (flows, findings, projects)
  modules/                 Synaps scanner modules (WASM)
  extensions/              Lua plugin scripts
  logs/                    Runtime logs
  backups/                 Database backups

Override the location with the HUGIN_HOME environment variable (must be an absolute path):

HUGIN_HOME=/srv/hugin hugin start

🔗Generate a Default Config

If you want to customize settings before starting:

hugin init

This writes a default config.toml to ~/.hugin/config.toml. See Configuration for the most common keys, and the Configuration Reference for the full schema.

🔗Export the CA Certificate

To export the CA certificate to a specific location:

hugin ca export --output ~/Desktop/hugin-ca.pem

Or print it to stdout:

hugin ca export --print

To install Hugin’s CA into the system trust store automatically (recommended over manual security/certutil commands):

hugin ca trust

The certificate is also downloadable from the API at http://127.0.0.1:8081/api/ca.pem while Hugin is running.