Interactive Terminal Sessions

Work with remote systems through persistent, stateful shell sessions - either through your AI assistant or browser-based terminals.

Overview

noBGP provides two ways to interact with terminals on your nodes:

1. AI-Managed Sessions - Your AI assistant creates and manages shell sessions for you
2. Browser Terminals - Web-based terminal access via published services

Both support full terminal emulation with interactive programs, control characters, and persistent state.

AI-Managed Sessions

When you ask your AI assistant to work with a node, it can create sessions - persistent shell environments that maintain state across multiple interactions.

How Sessions Work

Starting a Session

Simply ask your AI assistant:

Start an interactive shell session on my-server

or more specifically:

I need to work on api-server-1, start a shell session

Session State

Unlike one-off commands, sessions maintain:

• Current directory: cd changes persist
• Environment variables: Export variables that last
• Shell history: Previous commands are remembered
• Background jobs: Can run processes in background
• Shell context: Functions, aliases, etc.

Example Workflow

You: Start a shell on my-server

AI: I've started a shell session on my-server. What would you like to do?

You: Navigate to /var/www and show me what's there

AI: [Changes to /var/www and lists contents]

    drwxr-xr-x  5 www-data www-data  4096 Nov  1 10:30 html
    drwxr-xr-x  3 www-data www-data  4096 Oct 15 14:22 logs
    -rw-r--r--  1 www-data www-data   512 Oct  1 09:15 index.html

You: Check the size of the logs directory

AI: [Runs du -sh logs/]
    2.3G    logs/

You: Those logs are huge. Show me the oldest files in there

AI: [Navigates to logs/ and runs ls -lt | tail]
    [Shows oldest log files]

You: Delete all .log files older than 30 days

AI: I'll delete log files older than 30 days. This will free up space.

    [Runs find command]

    Deleted 47 old log files, freed 1.8GB

You: Exit the session

AI: Session closed. Is there anything else you'd like to do?

Multi-Step Operations

Sessions are perfect for complex tasks:

You: I need to build and deploy my Go application on prod-server

AI: I'll start a session and walk through the deployment.

    [Creates session]

    1. Pulling latest code from git...
       ✓ Updated to commit abc123

    2. Building the application...
       ✓ Build successful

    3. Running tests...
       ✓ All tests passed (42/42)

    4. Stopping old version...
       ✓ Service stopped

    5. Deploying new binary...
       ✓ Deployed

    6. Starting service...
       ✓ Service running

    Deployment complete! The new version is now live.

When to Use Sessions

Use sessions for:

• Multi-step procedures (build, test, deploy)
• Interactive file editing
• Navigating and exploring filesystems
• Long-running operations with progress monitoring
• Setting up environment for related tasks

Use one-shot commands for:

• Quick status checks (uptime, df -h)
• Single-purpose commands
• Automated scripts
• Queries that don't need context

Interactive Programs

Sessions support fully interactive programs:

Text Editors

You: Edit the nginx config file on web-server

AI: I'll open the nginx configuration in nano for you.

    [Opens nano with the config file]

    You can now edit the file. Let me know what changes you'd like to make.

You: Add a new server block for api.example.com on port 8080

AI: [Navigates in nano, adds the server block]

    I've added the server block. Here's what it looks like:

    server {
        listen 8080;
        server_name api.example.com;
        ...
    }

    Should I save the changes?

You: Yes, save and reload nginx

AI: [Saves file, exits nano, reloads nginx]
    ✓ Configuration saved
    ✓ Nginx reloaded successfully

Process Monitoring

You: Show me what processes are using the most CPU on my-server

AI: I'll open htop so you can see resource usage in real-time.

    [Launches htop]
    [AI describes what it sees]

    The top processes are:
    1. nginx (25% CPU)
    2. postgres (18% CPU)
    3. node (12% CPU)

    Would you like me to investigate any of these?

Database CLIs

You: Connect to PostgreSQL and show me the users table

AI: [Starts psql session]

    Connected to PostgreSQL. Running query...

    [Shows table contents]

    You have 1,247 users in the table. Would you like me to run any specific
    queries?

Control Characters

Sessions support all standard control characters:

Character	Function	Example Use
Ctrl+C	Interrupt current command	Stop a running process
Ctrl+D	End of input / logout	Exit shell or program
Ctrl+L	Clear screen	Clean up terminal
Ctrl+Z	Suspend process	Background a running program
Ctrl+R	Reverse search history	Find previous commands

Your AI assistant can send these when appropriate:

You: The command is taking too long, cancel it

AI: [Sends Ctrl+C]
    ✓ Command interrupted

You: Clear the terminal

AI: [Sends Ctrl+L]
    ✓ Terminal cleared

Browser-Based Terminals

For direct terminal access without going through your AI assistant, use published terminal services.

Creating a Browser Terminal

Ask your AI assistant:

Create a browser terminal for my-server with auth required

You'll receive a URL like https://xyz789.nobgp.com

Accessing the Terminal

1. Open the URL in your browser
2. Sign in with OAuth (if required)
3. You'll see a full terminal interface
4. Type commands directly

Browser Terminal Features

• Full terminal emulation: xterm-compatible
• 256 colors: Full color support
• Mouse support: Click to position cursor (where supported)
• Copy/paste: Standard browser shortcuts
• Resize handling: Adapts to window size
• UTF-8 support: International characters
• Keyboard shortcuts: All standard terminal shortcuts

Browser vs AI-Managed

Feature	Browser Terminal	AI-Managed Session
Access	Direct via web browser	Through AI conversation
Best for	Manual exploration	Automated tasks
Multi-step tasks	You type each command	AI executes sequence
Assistance	None	AI helps, explains, suggests
Speed	Direct, immediate	Conversational
Learning curve	Need to know commands	Describe what you want

Use browser terminals when:

• You know exactly what commands to run
• You need to paste complex commands
• You're comfortable with command line
• You want direct, fast access

Use AI-managed sessions when:

• You're not sure of exact commands
• You want help troubleshooting
• You need multi-step automation
• You want explanations of output

Session Management

Multiple Concurrent Sessions

You can have multiple sessions running:

You: Start sessions on all my web servers

AI: Starting sessions...
    ✓ Session 1: web-server-1
    ✓ Session 2: web-server-2
    ✓ Session 3: web-server-3

You: Check memory usage on all of them

AI: Checking all sessions...

    web-server-1: 45% (3.6GB / 8GB)
    web-server-2: 62% (5.0GB / 8GB)
    web-server-3: 38% (3.0GB / 8GB)

Session Timeouts

Sessions automatically close after:

• 30 minutes of inactivity (configurable)
• Explicit exit request
• Node goes offline

Before timeout, you'll usually receive a warning:

AI: Note: The session on my-server has been inactive for 25 minutes and will
    close in 5 minutes. Would you like to keep it alive?

Closing Sessions

Explicitly close when done:

You: I'm done with the session on my-server

AI: [Closes session]
    ✓ Session closed

or:

You: Close all open sessions

AI: Closing all sessions...
    ✓ 3 sessions closed

Advanced Techniques

Parallel Execution

Run commands across multiple nodes simultaneously:

You: Check disk space on all my production nodes in parallel

AI: Running df -h on all production nodes...

    [Creates sessions for all nodes]
    [Executes commands in parallel]

    Results:
    prod-web-1: 45% used (root: 22GB free)
    prod-api-1: 67% used (root: 16GB free)  ⚠️ Getting full
    prod-db-1: 89% used (root: 5GB free)   ⚠️ Low space!

    I recommend investigating prod-db-1 - it's running low on disk space.

Script Execution

Run complex scripts through sessions:

You: I have a deployment script. Run it on staging-server

AI: I'll execute your deployment script. Where is it located?

You: It's at /home/deploy/deploy.sh

AI: [Creates session]
    [Runs script]
    [Streams output in real-time]

    [Output from script...]

    ✓ Deployment completed successfully

File Transfers via Session

While file operations are better done through the file sharing system, you can use sessions:

You: Download the latest backup from db-server

AI: I'll use scp to transfer the backup file.

    [Uses session to initiate transfer]
    [Monitors progress]

    ✓ backup-2024-11-04.sql.gz downloaded (2.3GB)

Best Practices

1. Close Sessions When Done

Don't leave sessions idle:

✓ Good: "I'm done, close the session"
✗ Bad: Leaving session open indefinitely

2. Use Descriptive Requests

Help the AI understand context:

✓ Good: "Check if nginx is running on web-server-1"
✗ Less Good: "Check nginx"

3. Leverage AI Assistance

Take advantage of AI help:

You: Something is wrong with my web server, help me debug it

AI: I'll start a diagnostic session on your web server.

    [Checks various things]

    I found the issue: nginx is running but the application server on port 3000
    is not responding. Let me check the logs...

4. Confirm Destructive Actions

The AI will ask, but you can be explicit:

You: Delete old log files but ask me before actually deleting

AI: I found 47 log files older than 30 days (1.8GB total).

    Should I delete them?

You: Yes, proceed

AI: [Deletes files]
    ✓ Deleted 47 files

Troubleshooting

Session Becomes Unresponsive

Issue: Commands take forever or session hangs

Solutions:

• Send Ctrl+C to interrupt: "Cancel the current command"
• Close and create a new session
• Check if node is still online
• Verify network connectivity

Output is Garbled

Issue: Terminal shows weird characters or formatting

Solutions:

• Clear the terminal: "Clear the screen"
• Reset the terminal: "Reset the terminal"
• Close session and start fresh
• Check if output contains binary data

Can't Exit a Program

Issue: Stuck in vim, less, or other interactive program

Solutions:

• "Send Ctrl+C to interrupt"
• "Exit vim" (AI knows how!)
• "Force quit the program"
• Close session as last resort

Lost Track of Current Directory

Issue: Not sure where you are in the filesystem

Solutions:

You: Where am I in the filesystem?

AI: [Runs pwd]
    You're currently in /home/user/projects

Security Considerations

Session Privileges

Sessions run with the same privileges as the noBGP agent (typically root). This means:

• Commands execute with full system access
• Be careful with destructive commands
• The AI will warn about dangerous operations

Authentication

• Sessions are tied to your authenticated AI assistant
• OAuth token must be valid
• Sessions close if authentication expires

Audit Logging

All session activity is logged for security and debugging:

• What commands were executed
• Who initiated the session
• When commands ran
• What the output was

Next Steps

• Publishing Services - Learn how to create browser terminals
• Use Cases & Examples - See real-world session workflows
• MCP Tools Reference - Technical details of tty_exchange

FAQ

Q: Can multiple people use the same session? A: No, each session is tied to a single AI conversation. Create separate sessions for different users.

Q: What shell does the session use? A: By default, the system's default shell (usually bash). You can switch shells within the session.

Q: Can I run graphical programs? A: No, sessions are text-only. Use X forwarding or VNC for GUI applications.

Q: How much history is saved? A: Session history lasts for the lifetime of the session. Once closed, history is cleared.

Q: Can I resume a closed session? A: No, sessions can't be resumed. You'll need to create a new one.

Q: Do sessions persist if the node reboots? A: No, all sessions close when a node reboots. You'll need to create new sessions.