Sessions & Terminals

A session is a live shell or terminal multiplexer running on the agent. See the concept.

What you'll learn

• The seven session types
• Create + list + attach
• Browser access (ttyd)
• Send commands programmatically

Session types

The agent supports seven session backends, each implemented by a plugin:

Type	Plugin	What it gives you
TMUX	vibe-plugin-session-tmux	Full tmux session, persistent across disconnects, browser access via ttyd
WEZTERM	vibe-plugin-session-wezterm	WezTerm multiplexer
ZELLIJ	vibe-plugin-session-zellij	Zellij multiplexer
SSH	vibe-plugin-tool-ssh	Direct SSH connection to a configured target
TERMINAL	(built-in)	One-shot terminal (no multiplexing)
SCRIPT	(built-in)	Run a script to completion
CUSTOM	(your own plugin)	Anything else

Status lifecycle: PENDING → STARTING → RUNNING → STOPPED (clean) / ERROR (provider failure) / TERMINATED (explicit).

Create

vibecontrols sessions create \
  --name dev \
  --vibe-id <vibe-id> \
  --agent <agent-id> \
  --type TMUX \
  --command "bun run dev" \
  --working-directory /home/me/code/my-api

Optional: --env-var KEY=VALUE to pass extras beyond the vibe's environmentVariables.

The session's status flips to RUNNING once the provider confirms startup.

List

vibecontrols sessions list                    # current workspace
vibecontrols sessions list --vibe <vibe-id>
vibecontrols sessions list --agent <agent-id>
vibecontrols sessions list --status RUNNING

Browser access (ttyd)

For TMUX/WEZTERM/ZELLIJ session types, the agent runs ttyd on a port and tunnels it through the agent's outbound Cloudflare tunnel. The session's ttydUrl field is the browser-accessible URL — open it to attach from any browser.

Send commands programmatically

vibecontrols sessions send-command <session-id> "git pull && bun run build"
vibecontrols sessions send-keys <session-id> "C-c"   # tmux key syntax

Maps to the agent's REST endpoint POST /api/profiles/<profile>/tmux/<id>/send.

Terminate

vibecontrols sessions terminate <session-id>

Track time

The backend accumulates active session time in Session.accumulatedSeconds (BigInt). Useful for billing / time tracking.

Next steps

• Session sharing — invite a teammate or generate a share link
• Port forwarding & tunnels