Docs · Start

Install and log in.

You need osewa on your own machine and ssh access to the host. osewa login does the rest over ssh, once: it copies osewa to the host, enrolls your device's key and starts the server.

Get osewa on your machine

On Linux or macOS, amd64 or arm64:

$ curl -fsSL https://osewa.dev/install.sh | sh

It downloads the latest release for your OS and CPU, checks it against the release's SHA256SUMS and puts it at ~/.local/bin/osewa. Set OSEWA_VERSION=v0.1.0 for a particular release, or OSEWA_INSTALL_DIR for another directory. The macOS builds are signed and notarized. From then on osewa keeps itself up to date; see Auto-update.

From source

With Rust and Zig installed (Zig builds libghostty-vt):

git clone https://github.com/rjyo/osewa
cd osewa
make build      # needs Rust and Zig; writes bin/osewa

Put bin/osewa somewhere on your PATH.

Log in to a host

The target is anything you would pass to ssh: user@host, or an alias from ~/.ssh/config.

$ osewa login --service me@devbox

It prints what it did:

installed osewa on devbox
enrolled as "laptop" on devbox (devbox.example.com:7322)

From now on you reach the host by its name, here devbox: osewa attach devbox. See Sessions.

What login does

Creates your device key, client.key, if you don't have one yet.
Over ssh, checks the host's OS and CPU and any osewa it already has. If a copy with the same SHA-256 is there, nothing is sent. Otherwise it sends the binary, checks its size and hash, and puts it at ~/.local/bin/osewa.
Over a second ssh session, runs osewa enroll with your device's public key, then starts the server: as a user service with --service, or as a background daemon without it.
Dials the new server directly, for up to 10 seconds, to prove the port is reachable from where you are.
Saves the host, with the server's key pinned, to hosts.json. If the check failed, nothing is saved.

Use --service. Without it the server is a plain background process and won't come back after the host reboots. login says so, and you can run it again with --service at any time. See Running the server.

Hosts on another platform

login sends the host a build for the host's OS and CPU: osewa-linux-amd64, osewa-linux-arm64, osewa-darwin-amd64 or osewa-darwin-arm64. It looks for that file next to your osewa, then in $OSEWA_DIST. When the host is the same platform as your machine, it sends itself. So from a Mac to a Linux box you need a Linux build of osewa in one of those places.

Options

Flag	What it does
`--service`	Run the server as a systemd or launchd user service, so it survives reboots.
`--name N`	The name you'll use for the host. Defaults to the ssh target without `user@`.
`--addr host:port`	Where to dial the host. Defaults to the hostname ssh resolves (`ssh -G`) on port 7322. Set it when the host is reached at another address or port.
`--device N`	This device's name on the host. Defaults to your machine's hostname.
`--no-install`	Don't copy osewa; use the `osewa` already on the host's `PATH`.
`--no-check`	Save the host without dialing it first.

Open the port

The server listens on port 7322: TCP for the TLS WebSocket, UDP for QUIC. TCP is required; UDP is what makes it fast. If the host has a firewall or sits behind a cloud security group, open both. If only TCP gets through, osewa still works, over the WebSocket.

When the check can't reach the port, login stops and tells you:

the osewa server on devbox is running, but devbox.example.com:7322 can't be reached from here (...): open TCP port 7322 to this device (the host's firewall, a cloud security group), or log in again with --addr set to an address that reaches it; the host was not saved

Logging in again

Running login again for the same host is safe. It replaces the saved entry, re-enrolls the same device name, and only copies osewa if the host's copy differs. To change the port, see Changing the port.