# Hosts & connections

## The host editor

Press **⌘N** for a new host, or tap an existing host to edit it. The editor has
four tabs — **connection**, **advanced**, **forwarding**, **snippets** — and a
**connect** bar. On iPhone the same four sections appear as chips —
**connection**, **advanced**, **tunnels**, **snippets** — where connection
fields and tunnel rules are staged until you tap save (other edits apply
immediately, as on iPad); the editor is the same on both devices.

The connection tab holds the basics: **name**, **address**, **port**
(1–65535), **user**, **identity** (a key from your [keys](https://bambouville.com/docs/keys/) page), and
**password**. A password you type here is session-scoped: it's kept only for
the live session and never persisted. The one exception is a host set up
through [nearby setup](https://bambouville.com/docs/nearby-setup/) or [continuity](https://bambouville.com/docs/continuity/) that
authenticates by password — the password you type once on the new device is
kept as a saved credential in this device's keychain, never synced, and the
editor can change it later (saving replaces the stored password).

![The host editor showing its four tabs — connection, advanced, forwarding, snippets — with the connection fields and the connect bar.](https://bambouville.com/docs/assets/img/host-editor.png)

*Four tabs across the top, and a connect bar pinned to the bottom of every tab.*


## Transport: SSH or Mosh

Each host picks one transport:

- **ssh** — a single SSH connection; tmux tabs stay on the main session.
- **mosh** — a mosh terminal over UDP. Mosh keeps your session alive across
  Wi-Fi ↔ cellular roaming and sleep/wake, and feels snappier on lossy links.
  It requires `mosh-server` installed on the host. tmux tabs use a second SSH
  side channel. The [mosh page](https://bambouville.com/docs/mosh/) has the full story, including real
  scrollback.

Mosh's UDP traffic cannot traverse bastions: if you use mosh through a
[jump host](#jump-hosts) and the mosh server is unreachable, Tessera tells you
("mosh is unreachable through the jump chain…") and reconnects over SSH.

## Launch modes

- **auto-tmux** — attach to (or create) a per-host tmux session with a
  deterministic `tessera-XXXXXXXX` name, remembered across app reinstalls.
  The default, and the one that makes dropped connections harmless.
- **named tmux** — attach to a tmux session name you choose; names with
  invalid characters fall back to the auto-derived one.
- **custom** — a verbatim launch command. Over ssh it's sent to the login
  shell; over mosh it's run by `mosh-server new -- <command>`.

See [tmux](https://bambouville.com/docs/tmux/) for what the tmux modes give you, and
[port forwarding](https://bambouville.com/docs/port-forwarding/#mosh-and-forwarding) for how the launch
mode interacts with tunnels.

## Jump hosts

Any saved host can be used as an SSH bastion (ProxyJump): pick it in the host
editor. Chains nest — the jump host's own jump host extends the chain — and the
editor shows the resulting path ("a → b → host") with warnings for broken
chains.

- Each hop authenticates independently with its own identity or password.
  Password hops get a **password · \<hop name\>** field in the editor's
  jump-host section, kept only for the live session; connect stays disabled
  until every hop has one.
- Host-key prompts appear per hop, bastion first, each naming the endpoint
  being verified.
- A broken chain fails closed: if a jump host was deleted, the dependent host
  warns in its editor and the connection fails rather than silently going
  direct. Errors name the hop they came from ("jump host \<name\>: …").
- On the [free tier](https://bambouville.com/docs/unlimited-hosts/), a separately saved bastion uses a
  saved-host slot of its own.

## Advanced tab

- **os logo** — auto-detected on connect, or set manually (macos, ubuntu,
  debian, alpine, linux, raspbian).
- **tags** and **notes** — for your own organization.
- **environment variables** — one `KEY=value` per line; an optional leading
  `export ` is stripped. Values are passed to the remote shell verbatim —
  `$HOME`, `$(…)`, and quotes work as written.
- **terminal background** — a per-host override of the global
  [background](https://bambouville.com/docs/appearance/).

> Environment variables and startup snippets only run when the tmux session
> starts. If you change them for a host whose tmux session already exists,
> kill that session on the server to pick up the changes.

## Snippets

The snippets tab holds a **startup snippet**: commands sent immediately after
connecting (the same tmux caveat above applies).

## When a connection stalls

While a session comes up, the launch overlay names the stage it's in —
**connecting**, then for tmux hosts **starting tmux** (SSH) or
**attaching tmux** (mosh), then **attaching pane**. If one stage makes no
progress for about twelve seconds, the overlay says which stage is stuck
("still connecting — the handshake has not completed.") and offers a way
out instead of spinning:

- **edit host** — open the host editor, for when the address, port, or key
  is the problem,
- **retry** — tear the attempt down and reconnect from scratch,
- **back** — give up and return to your hosts. Backing out of a stalled
  attempt disconnects it fully — nothing is left running on the server.

The timer is per stage, so a slow connection that's still advancing never
trips it. If tmux itself can't come up — it isn't installed, the session
can't start, or the host's own dotfiles already launch tmux at login —
Tessera drops you into a plain shell with a banner saying exactly what
happened, rather than waiting on a tmux that will never answer.

![The launch overlay stalled while connecting: the stage caption reads connecting with the tmux session name beneath, a warning line reads still connecting — the handshake has not completed., and edit host, retry, and back buttons wait below.](https://bambouville.com/docs/assets/img/stall-notice.png)

*Twelve seconds without progress: the overlay names the stage and offers a way out.*

## Sessions

Tessera keeps multiple concurrent sessions open to any hosts. Auto-tmux hosts
are singletons — one tmux control session per host (per host and session name
for named tmux) — while custom-command hosts can have several ("name #2",
"name #3"). The sidebar's **active** section
lists every session, labeled "name (tmux)", "name (tmux: session-name)", or
"name #N", each with a disconnect button. On iPhone the same list is the
**sessions** tab.

Switch between sessions by tapping them, walking neighbors with **⌘⇧K** /
**⌘⇧J**, or opening the **⌘K** quick-switch palette: type to filter sessions
(most-recent first) and agents — prefix the query with `@` to scope to agents.

## Session restore

**settings → terminal → startup → previous connections** controls what happens
on a fresh launch:

- **ask** — shows a "reopen previous connections" sheet with
  "always reopen" / "reopen" / "not now".
- **always** — reconnects silently.
- **never** — starts clean.

On iPhone the chooser sheet is replaced by a single **restore on launch**
toggle. Only saved-host sessions with intact key material are restorable.

Coming back to the foreground works the same way but smarter: Tessera waits
for **every** open session to report its state before deciding what to
reconnect, so when several hosts drop at once — or a mosh session admits
only belatedly that it died — each one is reconnected, none stranded. While
that happens, the launch overlay counts the rest ("+2 more sessions
reconnecting").
Tessera is deliberately single-window (no multi-scene on iPad); the sidebar
and the palette — the tab bar and the switcher on
[iPhone](https://bambouville.com/docs/iphone/) — are how you move around.