Docs · Reference

Files and environment.

osewa keeps its state in a few plain files under your home directory, the same layout on your machine and on the host. Nothing is system-wide, and nothing needs root.

Config: ~/.config/osewa

Private: the directory must be mode 0700 and the files 0600, or osewa refuses to use them and says which chmod fixes it.

File	Where	What
`client.key`	your machine	This device's Ed25519 private key.
`hosts.json`	your machine	The hosts you have logged in to, with their pinned keys.
`server.key`	host	The host's Ed25519 private key.
`devices`	host	Enrolled devices, one JSON line each. Delete a line to revoke.
`*.lock`	both	Lock files for safe concurrent writes.

hosts.json

[
  {
    "name": "devbox",
    "addr": "devbox.example.com:7322",
    "server_key": "Qm9l…",
    "ssh": "me@devbox",
    "quic_port": 7322
  }
]

quic_port is filled in the first time the server tells the client it speaks QUIC, so the very first connection after login is WebSocket only. Editing addr by hand is fine; logging in again does the same.

On the host

Path	What
`~/.local/bin/osewa`	The binary login and update install.
`~/.local/state/osewa/server.log`	The server's log, for a daemon or a macOS service.
`~/.local/state/osewa/update.json`	When osewa last checked for a release, and what it found.
`~/.config/osewa/settings.json`	Settings from `osewa set`.
`$XDG_RUNTIME_DIR/osewa/`	Session sockets and `server.pid`. Without `XDG_RUNTIME_DIR` (macOS): `~/.local/state/osewa/run/`.
`~/.config/systemd/user/osewa.service`	The Linux service.
`~/Library/LaunchAgents/dev.osewa.server.plist`	The macOS service.

Environment variables

Variable	What it does
`OSEWA_CONFIG_DIR`	Use this directory instead of `~/.config/osewa`.
`XDG_CONFIG_HOME`	When set, config lives in `$XDG_CONFIG_HOME/osewa`, and the systemd unit under it.
`OSEWA_RUN_DIR`	Where session sockets and `server.pid` go.
`XDG_STATE_HOME`	When set, the log is `$XDG_STATE_HOME/osewa/server.log`.
`OSEWA_CARRIER`	`quic` or `ws` to use only that carrier, instead of racing both. Handy for testing a firewall.
`OSEWA_QUIC_CC`	QUIC congestion control: `cubic` (default), `bbr` or `newreno`.
`OSEWA_DIST`	A directory of `osewa-<os>-<arch>` builds for login and update to send to hosts. A released osewa downloads its own release's build when there's none.
`OSEWA_AUTO_UPDATE`	`auto`, `ask` or `off`, over `osewa set auto-update`.
`OSEWA_RELEASES`	Where releases are, instead of `https://github.com/rjyo/osewa/releases`: a mirror with the same layout.
`OSEWA_TRACE`	A directory to write JSON-lines traces to, for debugging.
`OSEWA_HOME`	On the host: an absolute path to use as sessions' home instead of the account's. For sandboxes and tests.

Sessions don't inherit the server's environment. They get HOME, USER, LOGNAME, SHELL and PATH from the account, the locale (LANG, LC_*) and TZ, and TERM=xterm-256color. Variables starting with OSEWA_ are never passed in.