Interactive Terminal Sessions

Work with remote systems through command sessions and browser-based terminals - either through your AI assistant or directly in your browser.

Overview

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

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

Both paths answer to the node's owner: the capability settings in the agent's own config govern AI-managed sessions and published terminal services alike, so a node that no longer serves the command domain refuses both. A published service adds its own authorization on top — who may reach the URL, whether a login is required.

AI-managed sessions work in two modes:

• One-shot commands — run df -h, systemctl status, etc. and get output immediately; the session closes when the command exits
• Interactive shell sessions — start bash (or another shell) and send multiple commands while maintaining state

AI-Managed Sessions

When you ask your AI assistant to work with a node, it uses the command MCP tool to run commands or start interactive shells.

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

State persistence depends on which pattern you use:

Interactive shell sessions (started with bash or another shell):

• cd changes persist across inputs
• Exported environment variables last for the session
• Shell history is remembered within the session
• Background jobs can be started
• Functions and aliases are available

One-shot commands (e.g., df -h, systemctl status):

• Each command starts in a fresh environment
• No state carries over between calls
• The session closes when the command exits

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?

Signals and Control

To interrupt or stop a running process, the AI assistant uses the signal field of the command tool rather than sending control character bytes.

Signal	Effect	When to Use
SIGINT	Interrupt (like Ctrl+C)	Cancel a running command
SIGTERM	Graceful termination	Stop a shell or long-running process
SIGHUP	Hangup	Reload some daemons
SIGQUIT	Quit with core dump	Force-quit a stuck process
SIGKILL	Unconditional kill	Last resort — process can't ignore this

You: The command is taking too long, cancel it

AI: [Sends SIGINT to the process]
    ✓ Command interrupted

You: Force-kill that process

AI: [Sends SIGKILL]
    ✓ Process killed

note

Always use the signal field to send control signals rather than sending raw control-character bytes via input. The signal field delivers signals reliably to the process group, while raw bytes depend on the process actively reading stdin.

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 close automatically when the underlying command exits — and for any session, there is a 30-second grace period after the command exits to retrieve the final exit code. For interactive shell sessions (started with bash):

• Sessions have a 1-hour idle timeout
• Session closes when you exit the shell (exit command or SIGTERM)
• Sessions also close if the node goes offline

Closing Sessions

One-shot commands close automatically — no action needed.

Interactive shell sessions can be closed by:

You: I'm done, exit the shell

AI: [Sends "exit\n" to the shell]
    ✓ Session closed

or via signal:

{ "command_id": "cmd_xyz", "signal": "SIGTERM" }

Polling Long-Running Commands

For commands that produce output over time, the AI polls using idle_timeout. The default is 5 seconds — if no output arrives for 5 seconds, the tool returns whatever was collected so far, and the command keeps running. The AI then polls again with the command_id.

For slow commands (large builds, network operations), a higher idle_timeout (e.g., 30 seconds) reduces the number of poll calls needed.

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

For sharing files across nodes, use the noBGP file sharing system rather than scp through a session. A network's shared drive appears at /mnt/nobgp/networks/<network> on all nodes in that network (agent 0.4.54+; before that, at the mount root — see What the mount contains), and you can browse it in the web dashboard under Networks → your network → Files.

You: I need to move a backup from db-server to app-server

AI: The easiest way is to copy it to /mnt/nobgp/networks/production on db-server.
    All nodes in the same network can access it from there.

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:

• Cancel the current command (the AI sends SIGINT via the signal field)
• 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:

• "Cancel the current command" (the AI sends SIGINT via the signal field)
• "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

AI-managed sessions run with the privileges the node's owner allows. By default sessions run as the node's configured user — typically the account that installed the agent. Where a node has none configured and its agent runs as root, the unelevated session is refused rather than started as the superuser: pass admin if that is what you meant, or configure an account with nobgp config --user (unelevated never means root). Set admin to run elevated instead; be careful with destructive commands, and note that the AI will warn about dangerous operations. Two things have to agree before that works: you must be an org Owner or Admin (a Member is refused with forbidden, not downgraded), and the node's owner must have left allow-admin on — a node with allow-admin: false refuses an explicit request for elevation rather than quietly running it unprivileged. See Execution identity.

Browser terminals start from the shell and account recorded in the published service, fixed at publish time by an Owner or Admin — and an elevated terminal can only be published, or later modified, by one. Because the stored identity carries over to whatever command the service is repointed at, changing an already-elevated service needs that same authority even when the change does not mention admin at all. The node still has the last word. Since agent 0.4.33 a terminal session answers the same allow-tools and allow-admin checks as an MCP call: a node that no longer serves the command domain refuses the terminal, and one with allow-admin: false refuses a service published to run as root instead of quietly running it as someone else.

Authentication

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

Audit Logging

Session lifecycle is audited: who opened the session, on which node, when, and the outcome. Command text and output are not recorded in the audit trail.

Next Steps

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

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: It depends on the session type. For interactive sessions, the AI starts bash (or another shell) explicitly. For browser terminals created without a specific command, the agent uses the configured user's login shell (from /etc/passwd on Linux/macOS, cmd.exe on Windows). One-shot commands also run through the session user's login shell (sh -lc style on Linux/macOS, cmd.exe /c on Windows), so shell quoting and expansion apply — but each starts in a fresh environment.

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.