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, and stdin: "open" — from router 0.4.155 a session's stdin is at end of file unless you ask for a pipe, so a shell started without it exits at once):

• 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. On Linux and macOS the signal field delivers a real signal to the whole process group, while raw bytes depend on the process actively reading stdin.

Windows has no signals — read what the node did

On a Windows node the names above are requests the agent serves with whatever mechanism the platform has, and the mechanisms are not equivalent:

Sent	What the node actually does
SIGINT	writes 0x03 to the process's stdin — so it interrupts a REPL and does nothing at all to a busy loop that never reads stdin
SIGTERM / SIGKILL	terminates the process tree, including a backgrounded grandchild that outlived cmd.exe. Windows has no graceful terminate for a non-console process, so the two are the same act
SIGHUP / SIGQUIT	refused — there is no mechanism to try, so nothing is attempted

From agent 0.4.86 the response says which of these happened rather than only that the call succeeded: signal_mechanism names the mechanism (kill, stdin_ctrl_c, terminate_job, terminate_process), signal_delivered says whether it was accepted, and signal_target says what it went to. signal_delivered: true with state: "running" means delivered and ignored — escalate to SIGKILL. See What a signal did.

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.link

Accessing the Terminal

1. Open the URL in your browser
2. Sign in — always: a terminal can never be published without sign-in, whatever your role
3. You'll see a full terminal interface
4. Type commands directly

A terminal opens for the people it names

A terminal opens for the node's controllers (its owner, and the organization's Owners and Admins) and for the addresses named on it — not for every member of the organization unless its controllers set all_org_members on that service, which a root terminal never accepts. A member who is not named meets the Access Required page and can request access; a controller answers it in the app or with service_share approve. See Who may visit a service.

An open session is re-checked while it runs (router 0.4.179): if the visitor's access is withdrawn, or the service changes under them, the session is closed with a notice rather than continuing on a grant that no longer exists.

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

Windows: stopping a terminal session needs agent 0.4.106

Through agent 0.4.105, stopping a terminal session on a Windows node — SIGTERM or SIGKILL on the session, or the session simply ending — closed the pseudo-console and nothing more. Nothing terminated the process behind it: Windows tore it down on its own schedule, with no ceiling and no fallback, so a program that ignores a console close carried on running with the session gone. Measured: timeout /t 60 /nobreak outlived the console close by more than 30 seconds, and anything backgrounded from cmd.exe could outlive the session indefinitely.

From agent 0.4.106 the session's process is held in a kill-on-close job — the same mechanism the command tool has always used on Windows — so a stop terminates the process and everything it spawned, and ending the session tears the same tree down.

SIGINT is unchanged: it is a Ctrl+C through the console, so it interrupts a program that reads its input and does nothing to one that does not. Windows has no graceful terminate for a non-console process, so SIGTERM and SIGKILL remain the same act. Linux and macOS were never affected — a signal there has always been a real signal to the process group. It applies to any terminal session on a Windows node — a browser terminal, or one opened against it with nobgp shell from another machine.

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 — and from router 0.4.146 polling counts as activity, so a session you keep reading stays alive even while the command itself says nothing. Until then the hour ran from the last byte of output, so a long silent job was reaped out from under a caller that was doing exactly what it was told to do.
• 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 (root omitted — admin is its old name and still works) 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, an omitted root runs the session as root, and the result reports root_used: true. Send root: "false" to force non-root work. On such a node it is refused rather than started as the superuser; configure an account with nobgp config --user to fix that (unelevated never means root). Send root: "true" to run as root; 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 hold root on that node — its owner, an org Owner or Admin, or a root entry on its access list — and the node's owner must have left allow-root on, a node with allow-root: false refusing an explicit request rather than quietly running it unprivileged. ⚠ You also need use of the node to open a session at all from router 0.4.179: being in the organization is no longer enough. See Execution identity.

Browser terminals start from the shell and account recorded in the published service, fixed at publish time by the node's controllers — its owner, or an org Owner/Admin — and a root terminal also needs root on the node, because publishing one is a standing grant rather than one call. Everyone the service admits gets that shell, and a terminal always needs sign-in: see Who can open a service. Because the stored identity carries over to whatever command the service is repointed at, changing an already-root service needs that same authority even when the change does not mention the field at all. The node still has the last word. Since agent 0.4.33 a terminal session answers the same allow-tools and allow-root checks as an MCP call: a node that no longer serves the command domain refuses the terminal, and one with allow-root: false refuses a service published to run as root instead of quietly running it as someone else.

A root terminal is itself a root grant

Naming someone on a terminal published to run as root gives them a root shell on that machine — with no entry on the node's access list, and the address may be outside the organization entirely. So on a root terminal: visitors are exact addresses only (never *@acme.com, never "all org members"), naming anyone who is not one of the node's controllers needs an explicit confirm_root: true, and the warning names every outside address. Removing the name closes it. A name stays when the person who added it stops being a controller — like any root grant, it stands until a controller removes it. See A root terminal is a root grant.

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.