Docs · Reference

Command line.

One binary, two sets of commands: client commands on your machine, host commands on the server. Flags may go anywhere among the arguments, and -flag works as well as --flag.

Client commands

Install osewa on a host over ssh, enroll this device and start the server. See Install and log in.

`--service`	Run the server as a user service.
`--name N`	The host's name here. Default: the target without `user@`.
`--addr host:port`	Where to dial it. Default: ssh's hostname for the target, port 7322.
`--device N`	This device's name on the host. Default: this machine's hostname.
`--no-install`	Use the osewa already on the host's `PATH`.
`--no-check`	Don't dial the host before saving it.

osewa attach [flags] <host> [id]

Attach to a session. Without an id: the only running session it can attach, or a new one if there are none. See Sessions.

`--take`	Take ownership from another device.
`--predict auto\|always\|never`	Local echo prediction. Default `auto`.
`--graphics auto\|always\|never`	Kitty graphics. Default `auto`.
`--clipboard-read`	Let host programs read your clipboard.
`--quiet`	No bottom-row notices when an agent is blocked or done.

Inside: ~. detaches, ~t or Ctrl-T (as a viewer) takes ownership, ~~ sends a ~. Escapes work after Enter.

osewa ls <host>

List sessions: ID TITLE SIZE OWNER ATTACHED IDLE STATUS STATE, where STATE is running, exited N or incompatible. Columns are padded with spaces, so scripts can split them.

osewa new <host> [-- argv...]

Start a session without attaching, and print its id. Runs your login shell, or argv.

osewa kill <host> <id>

End a session. This works on incompatible sessions too, which can't be attached.

osewa exec [--cwd dir] [--env K=V]... <host> -- argv...

Run a command on the host without a terminal; exits with its code. See Forwards and exec.

osewa forward <host> [bind:]port[:host:hostport]...

Forward local ports through the host, as ssh -L, until Ctrl-C.

osewa update [host]

Without a host: install the latest release over this osewa, checked against the release's SHA256SUMS, and restart the server here with it if one runs. With a host: copy this build to the host over osewa and restart its server with it. See Updating.

osewa set [auto-update [auto|ask|off]]

Show or change how osewa updates itself. auto, the default, installs a newer release that works with this one by itself: on your machine after a command, and on a server, which restarts into it once no forward or command is running. ask only says when a release is out. off doesn't check. A release that can't talk to this one is never installed by itself. See Auto-update.

osewa version [--json]

$ osewa version
osewa 0.1.0 (protocol 0, ghostty 83fb9562…, snapshot v1)
$ osewa version --json
{"ghostty":"83fb9562…","osewa":"0.1.0","snapshot_version":1,"version":0}

Two builds work together when version (the wire protocol) and snapshot_version match. ghostty is the libghostty commit the build links, for reference.

Host commands

osewa server [flags]

Serve sessions to enrolled devices. --daemon detaches into the background.

`--listen :7322`	Address and port, TCP and UDP.
`--name N`	The server's name. Default: the hostname.
`--daemon`	Run in the background, logging to `~/.local/state/osewa/server.log`.
`--no-quic`	TLS WebSocket only.
`--no-compress`	Don't compress WebSocket traffic.
`--no-forward`	Refuse port forwards.
`--no-exec`	Refuse commands without a terminal.

osewa service install [server flags] | uninstall

Run the server as a systemd (Linux) or launchd (macOS) user service, or remove it. install takes the server flags above, except --daemon.

osewa enroll [--port N]

Add a device. login runs this over ssh, with the request on stdin; you don't run it by hand. --port is the port it tells the device to dial (default 7322).

osewa holder

One session's process. The server starts it; you never do.

Exit codes

`0`	Success.
`1`	An error, printed as `osewa <command>: <message>`.
`2`	Bad arguments.
other	`attach` and `exec` exit with the remote program's code.