Concepts

Words

Word	Meaning
Project	A named group of tabs with a root directory. It's usually one codebase.
Tab	One layout of panes inside a project.
Pane	One terminal running one program.
Placement	Where a pane is: tiled in the layout, floating above it, or minimized. Any pane can move between the three without restarting its program.
Dock	The strip at the bottom of the window that holds minimized panes.
State	What a pane is doing: idle, running, waiting, done, failed, exited.
Attention	A pane that needs you: one that's waiting, done or failed.
Daemon	The background process that owns everything. The window calls it the server; the command line and this manual call it the daemon.

The daemon

• The first window or isc command that needs the daemon starts it. It runs in its own session, so it outlives whatever started it. You don't need to enable anything at login.
• isc daemon runs it in the foreground. A second daemon on the same socket refuses to start and says "a daemon is already running".
• It owns the projects, tabs, panes and their layout. Anything a window does to the layout, a command can do too, and each sees the other's changes immediately.
• It does no work while idle: no timers and no wakeups while nothing is happening.
• Only the same user can connect to it. There's no network listener and there never will be. To reach a pane on another machine, use ssh (see Attaching from a terminal). The window itself has no remote hosts.
• Any program running as you can drive the daemon through its socket: it can open and close panes, type into them and read them.
• The directory that holds the socket must be owned by you and closed to others (0700). The daemon creates it that way. If the directory already exists with wider permissions, the daemon refuses to start and says so.
• Socket paths have a length limit: about 108 bytes on Linux and 104 on macOS. A long INSENSICAL_SOCKET fails with "path must be shorter than SUN_LEN".
• If neither INSENSICAL_SOCKET nor XDG_RUNTIME_DIR is set (TMPDIR on macOS), there's nowhere to put the socket, and isc fails with "no per-user runtime directory".
• Stopping the daemon (isc kill-server, or a termination signal) kills every program in every pane and keeps the layout for the next start. Moving it to a new version doesn't stop it. Stopping, restarting and new versions covers both.

The daemon's environment

The daemon has the environment of whatever started it, and every pane inherits it.

• If a window opened from a launcher started the daemon, panes get the launcher's PATH, not a login shell's. A command that other terminals find might not be found.
• On macOS, a new pane's shell starts as a login shell, the same way the Mac's other terminals start it. So it reads the files that set PATH there (/etc/zprofile, ~/.zprofile), even though the application itself started with almost nothing in it. This applies to the login shell only: a shell setting runs exactly as written, and needs its own -l.
• A variable you change in a shell profile reaches new panes only through the shell's own start-up files, or after you stop the daemon with isc kill-server and start it again from an environment that has the variable. Stopping the daemon kills every program.
• Moving the daemon to a new version doesn't change its environment, because it's the same process.