Daemon Mode

Using TUIOS with persistent sessions via the daemon

Overview

TUIOS daemon mode enables persistent sessions that survive terminal disconnection. The daemon manages PTYs (pseudo-terminals) and stores session state, while clients attach/detach to view and interact with sessions.

Architecture

┌─────────────────────────────────────────────┐
│  TUIOS Daemon (Background Process)          │
│  ├─ Session Manager                         │
│  ├─ PTY Management (persistent terminals)   │
│  ├─ State Storage (windows, workspaces)     │
│  └─ Unix Socket Server                      │
└─────────────────────────────────────────────┘
           ▲                   ▲
           │                   │
     ┌─────┴─────┐       ┌─────┴─────┐
     │  Client 1 │       │  Client 2 │
     │  (TUI)    │       │  (TUI)    │
     └───────────┘       └───────────┘

Key Benefits:

• Sessions persist when you disconnect
• Multiple clients can attach to the same session
• Remote control via CLI commands
• Session state survives crashes

The daemon starts automatically when you create or attach to a session. You rarely need to manage it manually.

---

Session Lifecycle

Creating a New Session

Create a named session:

tuios new mysession

Create a session with auto-generated name:

tuios new
# Creates: session-0, session-1, etc.

Terminal Output

$ tuios new dev
Starting TUIOS daemon...
Creating session 'dev'
[detached from session 'dev']

The daemon starts in the background (if not already running) and you’re immediately attached to the new session.

Attaching to an Existing Session

Attach to a named session:

tuios attach mysession

Attach to the most recent session:

tuios attach

Create if missing (like tmux’s new-session -A):

tuios attach mysession -c

Use tuios attach with no arguments to quickly reconnect to your last session.

Detaching from a Session

While inside TUIOS, press the detach key:

Ctrl+B d     # Detach from session

The session continues running in the daemon. All windows and their processes remain active.

Listing Sessions

View all active sessions:

tuios ls

Example Output

$ tuios ls
╭─────────────┬─────────┬──────────┬────────────────────╮
│ Name        │ Windows │ Attached │ Created            │
├─────────────┼─────────┼──────────┼────────────────────┤
│ dev         │ 3       │ no       │ 2h ago             │
│ prod        │ 5       │ yes      │ 1d ago             │
│ session-0   │ 1       │ no       │ 3h ago             │
╰─────────────┴─────────┴──────────┴────────────────────╯

Alias: tuios list-sessions

Killing a Session

Terminate a session and all its windows:

tuios kill-session mysession

This closes all windows and terminates all processes in the session. Use with caution.

---

Daemon Management

Starting the Daemon

The daemon starts automatically, but you can start it manually:

tuios start-server

This command is hidden because users rarely need it. Sessions automatically start the daemon.

Running in Foreground (Debugging)

Run the daemon in the foreground with debug logging:

tuios daemon

With detailed message logging:

tuios daemon --log-level=messages

Debug Levels:

• off - No debug output (default)
• errors - Only error messages
• basic - Connection events and errors
• messages - All protocol messages except PTY I/O
• verbose - All messages including PTY I/O
• trace - Full payload hex dumps

Example Debug Output

$ tuios daemon --log-level=basic
TUIOS daemon started on /run/user/1000/tuios.sock (PID 12345)
Client client-1234 connected
Client client-1234 attached to session dev (TUI client, 1 clients total)

Stopping the Daemon

Shutdown the daemon (terminates all sessions):

tuios kill-server

This:

1. Disconnects all clients
2. Closes all PTYs
3. Removes the Unix socket
4. Exits the daemon process

All running sessions will be terminated. Attach to sessions and exit cleanly if you want to preserve shell history.

Viewing Daemon Logs

View recent daemon activity:

tuios logs

View more entries:

tuios logs -n 100

Follow logs in real-time:

tuios logs -f

Clear logs after viewing:

tuios logs --clear

Example

$ tuios logs -n 20
[14:23:45.123] [INFO] Client client-abc attached to session dev
[14:23:46.456] [DEBUG] PTY abc123 created
[14:24:10.789] [INFO] Session dev resized to 120x40

--- 20 log entries ---

---

State Persistence

What Gets Persisted

The daemon stores:

Window State:

• Window position, size, z-order
• Workspace assignment
• Custom window names
• Minimized state
• Terminal content (scrollback + screen)

Session State:

• Current workspace (1-9)
• Focused window per workspace
• Tiling mode enabled/disabled
• Master ratio for tiling
• BSP tree structure

PTY State:

• Running shell processes
• Terminal screen buffer
• Scrollback history (10,000 lines)
• Cursor position
• Terminal modes (mouse tracking, etc.)

Terminal content is fully preserved across disconnects. When you reattach, you’ll see exactly what was on screen, including all colors and formatting.

Reconnection Flow

When you attach to an existing session:

1. Daemon sends session state - Window positions, workspace, tiling mode
2. Client restores windows - Creates window objects from state
3. Daemon sends terminal states - Screen content, scrollback, cursor position
4. Client syncs PTY handlers - Connects to daemon’s PTY output streams
5. Client redraws UI - Renders everything exactly as it was

---

Multi-Client Sessions

Multiple clients can attach to the same session simultaneously.

Behavior

• Shared state - All clients see the same windows, workspace, focus
• Synchronized input - Changes from one client appear on all clients
• Size adaptation - Session size = minimum of all client sizes
• Independent detach - Clients can attach/detach independently

Size Handling

When multiple clients connect:

Client A: 200x50
Client B: 120x30  ← smallest
Client C: 160x40

Session size: 120x30 (minimum)

All clients render at 120x30. Clients with larger terminals see empty space.

For best experience, use similar terminal sizes across clients, or resize your terminal to match the session size shown in tuios ls.

Example Workflow

Terminal 1:

tuios new shared
# Work with 3 windows

Terminal 2 (simultaneously):

tuios attach shared
# See the same 3 windows, all changes sync

Terminal 3 (later):

tuios attach shared
# Session resizes to minimum of all 3 clients

---

Socket and PID Files

Socket Location

Linux/macOS:

/run/user/$UID/tuios.sock

Windows:

%LOCALAPPDATA%\tuios\tuios.sock

PID File

Linux/macOS:

/run/user/$UID/tuios.pid

Windows:

%LOCALAPPDATA%\tuios\tuios.pid

The PID file is removed on clean shutdown.

---

Troubleshooting

Daemon Won’t Start

Check for stale socket:

rm /run/user/$(id -u)/tuios.sock
tuios new

Check permissions:

ls -la /run/user/$(id -u)/
# Socket should be owned by you with 0700 permissions

Can’t Attach to Session

List sessions:

tuios ls
# Verify session exists

Check daemon logs:

tuios logs

Restart daemon:

tuios kill-server
tuios new

Session State Corrupted

Kill and recreate:

tuios kill-session mysession
tuios new mysession

This loses all windows and history in that session.

---

Advanced Usage

Scripting with Sessions

Create and populate a session via CLI:

#!/bin/bash
tuios new dev
sleep 1

tuios run-command --session dev NewWindow "Server"
tuios send-keys --session dev --literal "npm run dev" 
tuios send-keys --session dev Enter

tuios run-command --session dev NewWindow "Editor"
tuios send-keys --session dev --literal "nvim" 
tuios send-keys --session dev Enter

echo "Session 'dev' created with 2 windows"

Integration with tmux

TUIOS complements tmux:

# Use tmux for terminal multiplexing
# Use TUIOS for visual window management

tmux new-session -d -s build
tmux send-keys "tuios new build-ui" C-m

SSH Server Integration

Run TUIOS daemon sessions over SSH:

# On server
tuios ssh --port 2222

# From client  
ssh -p 2222 user@server
# Automatically attaches to TUIOS session

See SSH Server for details.

---

Comparison: Daemon Mode vs. Local Mode

Feature	Daemon Mode	Local Mode
Persistence	✅ Sessions survive disconnect	❌ Exits when closed
Multi-client	✅ Multiple attachments	❌ Single instance
Remote control	✅ CLI commands	❌ Not available
State recovery	✅ Full state + terminal content	❌ Lost on exit
Complexity	Daemon + socket	Single process
Use case	Persistent workflows	Quick sessions

Use daemon mode (default) for all regular work. Use local mode (tuios without session commands) only for quick tests.

---

See Also

Remote Control

Send commands to running sessions

SSH Server

Run TUIOS over SSH

Configuration

Daemon and session settings