Sessions.

A session is a shell, or any program, running on the host in its own process. It doesn't belong to a connection: you attach, detach, lose the network or close the laptop, and it keeps running until it exits.

The basics

osewa attach devbox            # attach to the only session, or start one
osewa ls devbox                # list sessions
osewa new devbox               # start another session, print its id
osewa new devbox -- htop       # start one running a program
osewa attach devbox 3f9c…      # attach to a session by id
osewa kill devbox 3f9c…        # end a session

attach with no id attaches to the host's session if there is exactly one, and starts a new one if there are none. With several, it lists them and asks you to pick. Ids are 32 hex characters, and commands need the whole id.

A new session runs your login shell, or the program after --. It starts in your home directory with a clean environment built from the host's account: HOME, USER, SHELL, a standard PATH (Homebrew first on macOS), your locale and time zone, and TERM=xterm-256color.

Detaching

At the start of a line, type ~. to detach. The session keeps running:

[osewa: detached; the session is still running]

The escapes, like ssh's, only work right after Enter:

Ctrl-C goes to the remote program, as you'd expect. When the program exits, attach prints [osewa: session ended, exit N] and exits with the same code.

When the network drops

Nothing to do. attach notices the dead connection, redials until the host answers, and resumes the session. Keys you typed in the meantime are numbered and delivered once. When it reconnects you get the current screen, not a replay of what you missed.

Owners and viewers

Any number of devices, or windows, can attach to one session. One is the owner: its keys reach the program and its window size is the session's size. The rest are viewers: they see the screen live, and what they type is dropped. A viewer sees:

viewing: laptop owns this session; Ctrl-T takes over

You become the owner when the session has none, when you already own it, or when you attach with --take. A viewer takes over with Ctrl-T, or ~t. If the owner goes away, ownership lapses 30 seconds after its last connection drops, so a quick reconnect keeps it.

Listing sessions

ID                                TITLE   SIZE    OWNER   ATTACHED  IDLE  STATUS   STATE
3f9c2a7e5b1d48e6a0c4f2b97d1e5a83  claude  120x40  laptop  1         -     working  running
9b0e41d7c2a35f8e6d1b0a7c4e92f315  vim     80x24   -       0         3h5m  -        running

OWNER

The owning device's name, or -.

ATTACHED

How many clients are attached now.

IDLE

How long since anyone was attached; - while someone is.

STATUS

What an agent in the session last reported: working, blocked, done or idle. Agents report it with OSC 7501; see Built for agents.

STATE

running, exited N, or incompatible: started by an older osewa build, so this server can't attach it (see below).

How long sessions live

• A running session lasts until its program exits, or until it has had nobody attached and no output for 24 hours.
• An exited session stays in the list for 24 hours, so you can see how it ended.
• Each session keeps up to 10 MiB of scrollback.
• Restarting the server doesn't touch sessions, nor does updating it to a build of the same protocol and snapshot version.
• An update that changes either leaves older sessions running but unattachable: their screens are kept in the old build's format. ls shows them as incompatible; finish what runs in them and end them with osewa kill.

attach options