Configuration

lasso has no config file. It is configured by command-line flags, environment variables, and the settings you change in its UI (which live in lasso.db; see Files and directories).

Flags go after lasso, lasso serve, lasso start or lasso restart. Where a flag has an environment variable, the variable sets the default and a flag on the command line wins. Credentials (UI_AUTH, MCP_OAUTH) are environment-only, so they never show up in ps.

lasso serve -h    # the authoritative list, with the defaults this build uses

Server flags#

Network and auth#

flag	env	default	effect
`-listen`		`127.0.0.1:8090`	The local listener: the address the web server binds, trusting whoever connects. lasso refuses to start on a non-loopback address unless `UI_AUTH` is set, `-require-access-header` is on, or `-insecure-no-auth` is passed. Never bind `0.0.0.0`: the terminal is a writable shell.
`-tailnet`	`LASSO_TAILNET`	`false`	Also serve HTTPS on this node's tailnet addresses, with tailscaled's certificate for its MagicDNS name, identifying each caller by tailscaled's whois of the connection. Needs MagicDNS and HTTPS certificates on the tailnet and, on Linux, `sudo tailscale set --operator=$USER`. Admits the node's owner unless `LASSO_ALLOW` is set. See Tailscale.
`-tailnet-port`	`LASSO_TAILNET_PORT`	the `-listen` port	Port for `-tailnet`.
`-listen-access`	`LASSO_LISTEN_ACCESS`	empty	A loopback address for `cloudflared` to target. Every request on it must carry a `Cf-Access-Jwt-Assertion` that verifies against `LASSO_ACCESS_TEAM` and `LASSO_ACCESS_AUD`, or it gets 403. lasso refuses to start without both variables or with a non-loopback address. See Cloudflare.
`-listen-serve`	`LASSO_LISTEN_SERVE`	empty	A loopback address for `tailscale serve` to target. lasso trusts the `Tailscale-User-Login` header there, so nothing else may forward to it; a request without one (a tagged device, Funnel) gets 403. Refuses a non-loopback address.
`-insecure-no-auth`		`false`	Deprecated; use `-tailnet`. Permits a non-loopback `-listen` with no auth at all, for a private interface such as a tailnet address.
`-require-access-header`	`LASSO_REQUIRE_ACCESS_HEADER`	`false`	Deprecated; use `-listen-access`. Answers 403 to every request on every listener without a Cloudflare Access identity, ahead of `UI_AUTH`. With `LASSO_ACCESS_TEAM` and `LASSO_ACCESS_AUD` set it verifies the `Cf-Access-Jwt-Assertion`; without them it only checks for a non-empty `Cf-Access-Authenticated-User-Email` header, which anything reaching the port can send. Counts as auth for the non-loopback rule. The variable is on for `1`, `true`, `yes` or `on`.
`-access-allowed-emails`	`LASSO_ACCESS_ALLOWED_EMAILS`	empty	Deprecated, with `-require-access-header`; use `LASSO_ALLOW`. Comma-separated allowlist for that gate, compared case-insensitively. Empty lets any identity Access vouched for through.
`-disable-self-update`	`LASSO_DISABLE_SELF_UPDATE`	`false`	Turn off the in-app self-update of a supervised source checkout: `POST /api/self-update` answers 403 and the UI hides the action. Use it where an agent must not be able to restart its own front door. Same truthy values as above.
`-dev`		`false`	Development mode: if the port is busy, bind the next free one (up to 50 tries); tee the log to `LASSO_DEV_LOG`; mount `/api/log`; never self-update. `mise run dev` sets it.

LASSO_TAILNET takes the same truthy values. See Deployment for which listener fits your setup, and Security for how they combine.

Terminals and herdr#

flag	env	default	effect
`-herdr-sock`	`HERDR_SOCKET_PATH`	`~/.config/herdr/herdr.sock`	The local herdr server's unix socket.
`-term-cmd`		`herdr`	Command ttyd runs in the main terminal.
`-term-nice`		`0`	When non-zero, launch the herdr terminal at this nice level (needs `RLIMIT_NICE` to lower it). `0` disables.
`-term-no-swap`		`false`	Launch the herdr terminal in a transient systemd scope with `MemorySwapMax=0`, so its memory is never swapped out.
`-spawn-ttyd`		`true`	Spawn and supervise ttyd as a child process, one per host, each on its own unix socket. `false` proxies to an external ttyd on `-ttyd-port` instead.
`-ttyd-port`		`7682`	Loopback port of the external ttyd. Only used with `-spawn-ttyd=false`.
`-poll`		`2s`	Fallback poll interval for noticing a pane's working directory change.
`-theme`		`auto`	`auto` follows herdr's `config.toml` live, falling back to `execution-associates` when nothing is configured. Any theme name forces that theme; `lasso serve -h` lists them. See Theming.

ttyd must be installed and on PATH for the default -spawn-ttyd=true.

Shared browser#

flag	env	default	effect
`-browser`	`LASSO_BROWSER`	search	Chromium for the shared browser: a path or a `PATH` name. Empty searches `PATH` (`chromium`, `chromium-browser`, `google-chrome-stable`, `google-chrome`, `chrome`), then Playwright's cache, then the macOS app bundles. `off` disables the shared browser.
`-browser-idle`	`LASSO_BROWSER_IDLE`	`15m`	Stop Chromium after this long with no `/cdp` client connected. `0` never stops it.
`-browser-cpu`	`LASSO_BROWSER_CPU`	`200%`	`CPUQuota` of the systemd user scope Chromium runs in (Linux). `off` or empty lifts it.
`-browser-mem`	`LASSO_BROWSER_MEM`	`2G`	`MemoryHigh` of that scope (Linux). `off` or empty lifts it. With both limits off, no scope is used.
`-browser-scale`	`LASSO_BROWSER_SCALE`	`2`	Device scale factor Chromium renders at, a number in (0, 4]. `1` is Chromium's default; higher is sharper on a HiDPI screen and costs raster CPU and larger agent screenshots.
`-browser-mcp`	`LASSO_BROWSER_MCP`	`chrome-devtools-mcp` on `PATH`	The chrome-devtools-mcp binary behind `/mcp`'s `browser_*` tools: a path or a `PATH` name. `off` leaves `/mcp` without browser tools. There is no `npx` fallback.
`-browser-mcp-max`	`LASSO_BROWSER_MCP_MAX`	`0`	Cap on live chrome-devtools-mcp processes, counted across every MCP session and browser. `0` means no limit.

The CPU and memory caps apply only when systemd-run and a user systemd manager (XDG_RUNTIME_DIR) are available; otherwise Chromium runs uncapped. Setting one of these variables to an empty string is the same as off. See Shared browser.

Environment variables#

Server#

variable	effect
`UI_AUTH`	`user:pass`. Turns on HTTP basic auth for the UI and every route except those listed in HTTP routes. A caller a network listener verified, or a lasso token with the `ui` scope, needs no password. Also lets a non-loopback bind start.
`MCP_OAUTH`	`client_id:client_secret`. Turns lasso into an OAuth 2.1 authorization server for its own `/mcp`, and gates `/mcp` (its `browser_*` tools included) and `/cdp` on a bearer token (or the `UI_AUTH` credentials, or a caller a network listener verified). Unset, `/mcp` is open and every OAuth route answers 404. See MCP OAuth.
`LASSO_ALLOW`	Who, among the callers a network listener (`-tailnet`, `-listen-access`, `-listen-serve`) verified, may in. Comma-separated: emails or tailnet logins, `tag:<name>` for tagged tailnet devices, `service:<client id>` for Access service tokens, and a `ui:` prefix on a machine entry to let it into the UI and `/api`. Unset: whoever Access admits on the access listener, and only the node's owner on the tailnet and serve listeners. The loopback listener never reads it. See Security.
`LASSO_ACCESS_TEAM`	Your Cloudflare Access team: `<team>`, `<team>.cloudflareaccess.com` or its `https://` URL. Needed by `-listen-access`; also makes `-require-access-header` verify assertions.
`LASSO_ACCESS_AUD`	The Access application's Audience (AUD) tag, comma-separated for several applications. Required with `LASSO_ACCESS_TEAM`.
`LASSO_HOSTNAMES`	Extra host names lasso answers to, comma-separated, `*.example.com` for a domain. lasso answers to IP addresses, `localhost`, this machine's hostname, its tailnet names and these; any other `Host` gets 421, except on the access listener. Add the name a reverse proxy publishes lasso under.
`TS_SOCKET`	tailscaled's LocalAPI socket, for `-tailnet` and `-listen-serve`. Default: `/var/run/tailscale/tailscaled.sock`, then `/run/tailscale/tailscaled.sock`, then the `tailscale` CLI.
`MCP_OAUTH_REDIRECT_URIS`	Comma-separated allowlist of redirect URIs for the pre-registered `MCP_OAUTH` client. Unset, that client accepts any `https` or loopback callback (the consent screen shows the target).
`LASSO_DIR`	lasso's state directory. Default `~/.lasso`. Moves `lasso.db`, plugins, plugin data, installed themes, the shared browsers' data directories, and the worktree, scratch, upload and prompt directories. It does not move `lasso start`'s PID and log files, which stay in `~/.lasso`. When set, lasso uses this same path on remote hosts too, instead of each host's `~/.lasso`.
`LASSO_PUSH_CONTACT`	The contact the VAPID JWT names to push services, e.g. `mailto:you@example.com`. Default: the origin the device subscribed from.
`LASSO_ISB`	The isb CLI for sandboxed plugins (1.0 or later): a path or a `PATH` name. When set, nothing else is tried. Default: the first new-enough of `isb` on `PATH` and the newest mise install of isb. `off` disables sandboxed plugins (trusted ones still run).
`ISB_SERVE_SOCKET`	Where lasso looks for `isb serve`'s unix socket to check it is running before starting a plugin sandbox. Default `$XDG_RUNTIME_DIR/isb/serve.sock`.
`LASSO_BROWSER_ARGS`	Extra Chromium flags, split on whitespace. `--no-sandbox` here is the knowing workaround for a Chromium whose sandbox cannot start.
`LASSO_BROWSER_MCP_ARGS`	Extra chrome-devtools-mcp flags, split on whitespace (e.g. `--slim`).
`HERDR_SOCKET_PATH`	Default for `-herdr-sock`.
`HERDR_CONFIG_PATH`	The local herdr `config.toml` lasso reads its theme from and writes theme changes to. Default `$XDG_CONFIG_HOME/herdr/config.toml`, else `~/.config/herdr/config.toml`, which is herdr's own order. On a remote host lasso resolves the same chain from that host's environment.
`XDG_RUNTIME_DIR`	Its presence (with `systemd-run`) is what lets lasso cap the shared browser in a systemd user scope.
`DO_NOT_TRACK`, `LASSO_TELEMETRY`	`DO_NOT_TRACK=1` or `LASSO_TELEMETRY=0` (also `false`, `off`, `no`) holds anonymous usage analytics off whatever the setting says.
`LASSO_TELEMETRY_HOST`, `LASSO_TELEMETRY_KEY`	Send analytics to another PostHog host or project, for testing. An empty key sends nothing.
`LASSO_TELEMETRY_DEBUG`	`1` logs analytics send failures, which are otherwise silent.
`LASSO_COMPOSER_GUARD`	On by default. Before the chat view types a message into an agent pane, lasso checks that pane's input box holds no unsent draft and refuses if it does. `false` or `0` turns that check off, as an escape hatch if a harness's screen layout changes and the check misfires.

The usage footer reads each provider's credentials the way that provider's own tools do. These variables are consulted as part of that:

variable	effect
`CODEX_HOME`	Where Codex keeps `auth.json`. Default `~/.codex`.
`KIMI_CODE_HOME`	Where Kimi Code keeps `credentials/kimi-code.json`. Default `~/.kimi-code`.
`ZAI_API_KEY`, `GLM_API_KEY`	A Z.ai API key, tried in that order.
`ANTHROPIC_BASE_URL` with `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY`	Used for Z.ai only when the base URL points at Z.ai, mirroring Z.ai's Claude Code setup.

CLI clients#

Read by lasso notify, open, mcp, connect, plugin and closeme (see CLI for which reads what):

variable	effect
`LASSO_URL`	Full base URL of the lasso to talk to. Wins over `LASSO_LISTEN`.
`LASSO_LISTEN`	`host:port` of a local lasso. Default `127.0.0.1:8090`.
`LASSO_MCP_TOKEN`	Bearer token to send, for a lasso with `MCP_OAUTH`. Also `lasso connect`'s default `-token`.
`UI_AUTH`	Sent as basic auth when set.
`HERDR_PANE_ID`	The caller's pane, set by herdr in every pane. `closeme` requires it; `notify` and `open` use it to name the calling agent.
`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_CONFIG_HOME`	Where `lasso connect` finds Claude Code's, Codex's and OpenCode's config.

Source installs and development#

variable	effect
`LASSO_SRC_DIR`	The git checkout `lasso update` and the in-app self-update pull. Default: the directory holding the running binary.
`LASSO_SYSTEMD_UNIT`	The `systemctl --user` unit they restart. Default `lasso`.
`LASSO_DEV_LOG`	With `-dev`, the file the backend and browser logs are teed into, truncated at startup. Default `/tmp/lasso-dev.log`.

What lasso sets for others#

A plugin's MCP server gets LASSO_PLUGIN_DATA, its writable data directory (see Plugins). None of lasso's own credentials (UI_AUTH, MCP_OAUTH, LASSO_MCP_TOKEN) reach the processes it starts for others: Chromium gets lasso's environment minus those three, and chrome-devtools-mcp and trusted plugin servers get a minimal allowlisted environment.