Remote Access

Hefty runs a built-in HTTP server for the web UI and API. The http block in your hefty.conf controls how it binds, what hostname it advertises, and whether it runs in headless mode.

Default Configuration

hefty {
  http {
    port = 41890
    host = "0.0.0.0"
    hostname = "localhost"
    external-url = ""
    headless = false
  }
}

Settings Reference

Setting	Default	Description
`port`	`41890`	The TCP port for Hefty's unified server. The env var override `HEFTY_PORT` is documented on the Advanced page.
`host`	`"127.0.0.1"`	The network interface to bind to. `127.0.0.1` means localhost only; `0.0.0.0` means all interfaces. The env var override `HEFTY_HOST` is documented on the Advanced page.
`hostname`	`""` (auto-detected)	The advertised name the server uses for link generation. When empty, Hefty auto-detects the machine hostname.
`external-url`	`""` (disabled)	The public URL Hefty uses in generated links. Useful behind reverse proxies or NAT.
`headless`	`false`	When `true`, Hefty starts without opening the desktop GUI. The env var override is `HEFTY_HEADLESS`.

host vs hostname

Tip

host is the bind address — it controls which network interface Hefty listens on. hostname is the advertised name — it controls the server name used to generate URLs in the UI, API responses, and email links. They serve completely different purposes.

Security Considerations

Warning

Setting host to 0.0.0.0 exposes Hefty on all network interfaces. On untrusted networks (public Wi-Fi, shared office LANs) this means anyone who can reach the machine can access the Hefty web UI and API. Use firewall rules, a reverse proxy with TLS and authentication, or restrict the bind address to a specific interface.

See the Advanced page for the HEFTY_PORT and HEFTY_HOST environment variable overrides.

Common Scenarios

LAN Access

Setting host to 0.0.0.0 makes Hefty reachable from other machines on the same network:

hefty {
  http {
    host = "0.0.0.0"
  }
}

Be aware of the security considerations above — on untrusted networks, bind to a specific interface or use a firewall.

Headless Server

Combining headless = true with host = "0.0.0.0" is the typical setup for a remote server or Docker container where there is no desktop:

hefty {
  http {
    host = "0.0.0.0"
    headless = true
  }
}

You can also set HEFTY_HEADLESS as an environment variable instead of editing the config file.

Reverse Proxy

When running behind nginx, Caddy, or similar, set external-url to the public-facing URL so that generated links point to the proxy. Keep host at 127.0.0.1 so Hefty only accepts local connections from the proxy:

hefty {
  http {
    port = 41890
    host = "127.0.0.1"
    external-url = "https://hefty.example.com"
  }
}

Environment Variables

HEFTY_HEADLESS — sets headless = true. Set this environment variable to run Hefty without the desktop GUI.

The HEFTY_PORT and HEFTY_HOST environment variables are documented on the Advanced page.