AI Guardian
Private management console
📄
This is a Template — Give This Page to Your AI
This is a reference guide showing what an AI management console looks like. Your AI can recreate this entire page for your own setup — with your real server details, a password gate, and everything working.

Just give your AI this URL and say:
"Recreate this entire page for our setup — replace all the placeholder values with our real server info, save it as a password-protected page I can always access, and set up everything described in it."
Your AI will handle the rest: fill in your IP address, usernames, paths, service names, scripts — and deliver you a working management console.

[Your AI Name] Guardian

Your AI management console — monitor, restart, and connect with one word

Template — Customize for Your AI
Server
Your VPS Provider
IP Address
YOUR.SERVER.IP
SSH User
youruser
SSH Port
22 (standard)
OS
Linux (Ubuntu)
Quick Connect
Copy & run in Mac Terminal
SSH in
ssh
One-liner restart
ssh 'bash /home/youruser/your-ai-project/tools/yourai-restart.sh'
Join running session
cd /home/youruser/your-ai-project && tmux attach -t $(cat .current_session)
Run this after SSHing in. If you get "sessions should be nested" — you're already in tmux. Use the [yourai] bash function instead (see Section 7).
Check sessions
tmux list-sessions
1. Health Check
Verify [Your AI Name] is alive and the session is active
  1. 1
    Open Terminal on your Mac and connect
    SSH into your AI's server
    ssh 
    You should be dropped into a Linux shell. If you see a password prompt, your SSH key is not set up — see Section 6 below for the one-time key setup.
  2. 2
    Check for active tmux sessions
    tmux list-sessions
  3. 3
    Read the result
    Healthy — sessions exist
    56: 1 windows (created ...)
    yourai-unified: 1 windows ...
    Unhealthy — no sessions
    no server running on /tmp/tmux-1000/default
    If sessions exist, your AI's environment is intact. Numbered sessions (45, 47, 52, etc.) are normal — Claude Code creates a new numbered session on each restart. After a manual restart you will see a session named yourai-recovery-YYYYMMDD-HHMM.
  4. 4
    Optional deeper check — systemd service status
    Check all AI services
    systemctl status yourai-session.service --no-pager
    systemctl status yourai-telegram.service --no-pager
    Both should show active (running). If either shows failed, restart it (see Section 4).
  5. 5
    Disconnect when done
    exit
2. Live Monitoring
Watch exactly what [Your AI Name] is doing in real time
  1. 1
    SSH in and list sessions
    ssh 
    tmux list-sessions
  2. 2
    Attach to the active session (use the highest numbered session)
    Attach (replace 56 with your session number)
    tmux attach -t 56
    You are now watching your AI's live terminal. You can scroll up to read history with Ctrl+B [ then arrow keys. Press q to exit scroll mode.
  3. 3
    Detach safely without disturbing your AI
    Safe detach shortcut
    Ctrl+B then D
    Always detach with Ctrl+B then D. Never close the terminal window while attached — this can interrupt your AI's active work and may require a restart.
  4. 4
    Read-only snapshot (no attachment needed)
    Capture last 30 lines of session output
    tmux capture-pane -t 56 -p | tail -30
    Safe to run anytime — does not interrupt your AI. Replace 56 with whatever session number tmux list-sessions shows.
3. Restart [Your AI Name]
Full clean restart when your AI is unresponsive or stuck
  1. 1
    One-liner restart from your Mac (no need to SSH first)
    Full restart in one command
    ssh  'bash /home/youruser/your-ai-project/tools/yourai-restart.sh'
  2. 2
    Or restart manually from inside the server
    SSH in
    ssh 
    Run the restart script
    bash /home/youruser/your-ai-project/tools/yourai-restart.sh
    The script kills old processes, creates a fresh tmux session, launches Claude Code, restarts the messaging bridge, and sends you a confirmation message automatically.
  3. 3
    Wait for confirmation message
    The restart takes approximately 60–90 seconds to complete. You will receive a message from your AI confirming it is back online. Wait for it before taking any further action.
  4. 4
    Verify it is back
    Confirm new session exists
    tmux list-sessions
    You should see a session named yourai-recovery-YYYYMMDD-HHMM. That is your AI's fresh start.
  5. 5
    Disconnect
    exit
Safe to run anytime. The restart script is idempotent — safe to run even if your AI is mid-session. It creates a clean fresh start without losing vault or memory data (all data lives in the project directory, not in the process).
4. Services & Infrastructure
Manage the systemd services that keep [Your AI Name] always running
These services start automatically on boot and restart on crash. You rarely need to touch them directly.
ServiceWhat It Does
yourai-session.serviceKeeps Claude Code + messaging bridge always running
yourai-telegram.serviceMessaging bridge (2-way messaging with [Your Name])
yourai-portal.servicePortal UI (port YOUR_PORT)
yourai-logserver.serviceWeb conversation logging (port YOUR_PORT)
yourai-comms-gateway.serviceCommunications gateway for inter-AI coordination
Check all AI services at once
systemctl status yourai-*.service --no-pager
Restart a specific service
sudo systemctl restart yourai-session.service
sudo systemctl restart yourai-telegram.service
View live service logs
journalctl -u yourai-session.service -f
journalctl -u yourai-telegram.service -f
5. Quick Reference
Every important detail at a glance
Server IPYOUR.SERVER.IP
SSH useryouruser
SSH port22 (standard)
Project root/home/youruser/your-ai-project
Restart scripttools/yourai-restart.sh
Messaging bridgetools/messaging_bridge.py
Session name after restartyourai-recovery-YYYYMMDD-HHMM
Messaging bridge loglogs/messaging_bridge.log
Session manager loglogs/session_manager.log
Detach from tmuxCtrl+B then D
Read-only snapshottmux capture-pane -t [N] -p | tail -30
Password[Choose your own password]
🔑
6. Mac SSH Key Setup
One-time setup so you never need a password to SSH in
If SSH asks for a password when you try to connect, do this once and SSH will never ask again.
  1. 1
    Check if you already have an SSH key on your Mac
    Mac Terminal
    ls ~/.ssh/id_ed25519.pub ~/.ssh/id_rsa.pub 2>/dev/null
    If you see a file path, you have a key — skip to step 3. If you see "No such file", generate one first.
  2. 2
    Generate a new SSH key (if you don't have one)
    Mac Terminal
    ssh-keygen -t ed25519 -C "yourai-access"
    Press Enter three times to accept defaults (no passphrase needed).
  3. 3
    Copy your public key to the server
    Run from Mac Terminal
    ssh-copy-id [email protected]
    Enter the server password once when prompted. After this, SSH connects without a password from this Mac forever.
  4. 4
    Add a one-word Terminal shortcut
    Add to ~/.zshrc (Mac)
    echo "alias myai='ssh -t [email protected] bash /home/youruser/your-ai-project/tools/connect-yourai.sh'" >> ~/.zshrc && source ~/.zshrc
    After running this, just type myai in Terminal — it SSHs in and drops you directly into the live AI session. Same session as the portal. One word, instant connection. The connect-yourai.sh script reads .current_session so it always finds the right tmux session, even after restarts.
7. One-Word Terminal Setup (For Anyone)
Type one word in Terminal → land in your AI's live session. Two scripts, zero friction.
Want to type a single word (like myai) and instantly land in your AI's live terminal session? This is how. Two steps: one script on the server, one script on your Mac. That's it.
💡 How it works: Your AI runs inside a tmux session on a server. A file called .current_session always tracks which session is active. When you type your magic word, it SSHs in and attaches to whatever session your AI is currently running in — same session as the portal. Session numbers change on every restart, but this always finds the right one.
  1. 1
    What you need before starting
    • A Linux server (VPS) with your AI running inside tmux
    • Your server's IP address and username
    • Your server password (you'll only need it once)
    • A Mac with Terminal (or Linux/WSL)
  2. 2
    Ask your AI to create the server-side connect script
    Tell your AI to create this file on the server. Replace the path with wherever your AI's project lives.
    connect-ai.sh — save on your server
    #!/bin/bash
    # Connect to the active AI session
    # YOUR AI should update .current_session in its startup script
    
    PROJECT_DIR="/home/youruser/your-ai-project"
    SESSION=$(cat "$PROJECT_DIR/.current_session" 2>/dev/null)
    
    if [ -z "$SESSION" ]; then
        echo "No active AI session found."
        tmux list-sessions 2>/dev/null
        exit 1
    fi
    
    if tmux has-session -t "$SESSION" 2>/dev/null; then
        exec tmux attach -t "$SESSION"
    else
        echo "Session '$SESSION' not found. Available:"
        tmux list-sessions 2>/dev/null
        exit 1
    fi
    Your AI also needs to make it executable: chmod +x connect-ai.sh
    Important: Your AI's startup/restart script must write the current tmux session name to .current_session every time it starts. Example: echo "$(tmux display-message -p '#{session_name}')" > .current_session
  3. 3
    Run this ONE-TIME setup script on your Mac
    Copy the script below. Save it as setup-myai.sh on your Mac. Open Terminal and run: bash setup-myai.sh
    It will ask you 4 questions, then set everything up automatically. You never need to run it again.
    setup-myai.sh — save on your Mac, run once
    #!/bin/bash
    # ONE-TIME SETUP: Adds a one-word command to connect to your AI
    # Run once: bash setup-myai.sh
    
    echo ""
    echo "=== One-Word AI Terminal Setup ==="
    echo ""
    
    # Ask the 4 questions
    read -p "What word do you want to type to connect? (e.g. myai): " COMMAND_NAME
    read -p "Server IP address (e.g. 123.45.67.89): " SERVER_IP
    read -p "Server username (e.g. youruser): " SERVER_USER
    read -p "Full path to connect script on server (e.g. /home/youruser/project/tools/connect-ai.sh): " SCRIPT_PATH
    
    echo ""
    echo "--- Setting up SSH key (so you never need a password) ---"
    
    # Generate SSH key if needed
    if [ ! -f ~/.ssh/id_ed25519 ] && [ ! -f ~/.ssh/id_rsa ]; then
        echo "No SSH key found. Generating one..."
        ssh-keygen -t ed25519 -C "${COMMAND_NAME}-access" -f ~/.ssh/id_ed25519 -N ""
        echo ""
    fi
    
    # Copy key to server
    echo "Copying your SSH key to the server (enter your server password when asked)..."
    ssh-copy-id "${SERVER_USER}@${SERVER_IP}"
    
    echo ""
    echo "--- Adding the '${COMMAND_NAME}' command ---"
    
    # Detect shell config file
    if [ -f ~/.zshrc ]; then
        SHELL_RC=~/.zshrc
    elif [ -f ~/.bashrc ]; then
        SHELL_RC=~/.bashrc
    else
        SHELL_RC=~/.zshrc
        touch "$SHELL_RC"
    fi
    
    # Remove any old alias with this name
    sed -i.bak "/alias ${COMMAND_NAME}=/d" "$SHELL_RC" 2>/dev/null
    
    # Add the new alias
    echo "" >> "$SHELL_RC"
    echo "# Type '${COMMAND_NAME}' to connect to your AI" >> "$SHELL_RC"
    echo "alias ${COMMAND_NAME}='ssh -t ${SERVER_USER}@${SERVER_IP} bash ${SCRIPT_PATH}'" >> "$SHELL_RC"
    
    echo ""
    echo "Done! Close this terminal, open a new one, and type:"
    echo ""
    echo "    ${COMMAND_NAME}"
    echo ""
    echo "You'll land directly in your AI's live session."
    echo "To disconnect safely: press Ctrl+B then D"
    echo ""
  4. 4
    Test it
    Close Terminal completely, reopen it, and type your word:
    Your magic word
    myai
    You should land directly in your AI's live terminal session. Same session as your portal. To disconnect safely, press Ctrl+B then D (this detaches without stopping your AI).
The -t flag is critical. The alias MUST include -t in the SSH command (forces terminal allocation). Without it, tmux refuses to attach. If your alias doesn't work, this is the first thing to check.
🔗 Why a connect script instead of a hardcoded session number? Your AI's tmux session number changes every time it restarts (session 1, then 5, then 12...). The connect script reads .current_session dynamically so your one-word command never goes stale.
🔒
8. OAuth Reauthorization (When Claude Disconnects)
Fix expired tokens, missing PATH, dead messaging bridge, or a full nuclear reset
💡 When to use this section: Your AI stopped responding, messaging went silent, or Claude Code is showing an OAuth/401 error. Pick the scenario that matches what you're seeing.
SCENARIO A OAuth Token Expired — 401 Error
Error message: OAuth token has expired. Please obtain a new token or refresh your existing token. This is the most common issue. Takes ~5 minutes.
  1. 1
    SSH in, then make sure you are the correct user
    tmux sessions run as your project user, not root. If you SSH in as root, you won't see any sessions.
    Mac Terminal
    ssh 
    On the server — check who you are
    whoami
    # If it says "root", switch to your user:
    su - youruser
  2. 2
    Attach to the running tmux session
    Find and attach to the session
    tmux list-sessions
    tmux attach
    You'll see Claude Code showing the OAuth error. That's expected.
  3. 3
    Exit Claude Code first (critical)
    You cannot run claude login from inside Claude Code. Exit it first.
    Stop Claude Code
    Ctrl+C
    # If the prompt doesn't return, try: /exit  or press q
    You should now see a plain bash prompt.
  4. 4
    Run claude login
    From the bash prompt
    claude login
    Claude Code will output a URL. Copy that entire URL.
  5. 5
    Open the URL in your browser and authorize
    Paste the URL on your Mac or phone. Click Authorize. If it gives you a code to paste back in the terminal, paste it and press Enter. If it just says "success", the terminal received it automatically.
  6. 6
    Start Claude Code fresh, then detach
    Restart your AI
    cd /home/youruser/your-ai-project
    claude
    Your AI will wake up and run its startup protocol. Once you see activity, detach safely: press Ctrl+B then D.
SCENARIO B Claude Code Not Found / PATH Issue
Symptom: claude: command not found when you try to run claude or claude login.
  1. 1
    Check if Claude Code is installed but just not on PATH
    ls ~/.local/bin/claude
    If the file exists, fix PATH temporarily then make it permanent:
    Fix PATH
    export PATH="$HOME/.local/bin:$PATH"
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
  2. 2
    If not installed, reinstall Claude Code
    Reinstall + fix PATH
    curl -fsSL https://claude.ai/install.sh | bash
    export PATH="$HOME/.local/bin:$PATH"
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
    which claude
    After install, which claude should print a path. Then continue with Scenario A step 4 (claude login).
SCENARIO C Messaging Bridge Down
Symptom: Your AI is running (Claude Code active) but you're not getting Telegram responses. Bridge may show connection failures in logs.
  1. 1
    Check bridge status
    Check Telegram bridge service
    systemctl --user status yourai-telegram.service --no-pager
    journalctl --user -u yourai-telegram.service --no-pager -n 20
  2. 2
    Kill and restart manually
    Manual restart (use if systemd backed off)
    pkill -f telegram_bridge.py
    rm -f /home/youruser/your-ai-project/.telegram_bridge.pid
    cd /home/youruser/your-ai-project
    nohup python3 tools/telegram_bridge.py >> logs/telegram_bridge.log 2>&1 &
    Or restart via systemd
    systemctl --user restart yourai-telegram.service
  3. 3
    Verify the bridge is working
    Watch the log (Ctrl+C to stop)
    tail -f /home/youruser/your-ai-project/logs/telegram_bridge.log
    You should see it connecting without errors. If it keeps failing, check your Telegram bot token in the config file.
SCENARIO D Nuclear Option — Kill Everything and Restart
When to use: Multiple services are down, Claude Code won't start, OAuth is broken, nothing above is working.
  1. 1
    SSH in as your user (switch from root if needed)
    ssh 
    # If you land as root:
    su - youruser
  2. 2
    Kill everything
    Nuclear kill sequence
    tmux kill-server
    pkill -f telegram_bridge.py
    pkill -f claude
  3. 3
    Clean up stale lock files
    cd /home/youruser/your-ai-project
    rm -f .telegram_bridge.pid .current_session .agentmail_monitor.pid .boop_executor.pid
  4. 4
    Restart via systemd and wait
    sudo systemctl restart yourai-session.service
    sleep 30
    tmux list-sessions
    If a session appears, run tmux attach. If Claude Code shows an OAuth error, follow Scenario A steps 3–6 to reauthorize.
  5. 5
    If no session was created, start one manually
    Manual session start
    tmux new-session -s ai-manual
    cd /home/youruser/your-ai-project
    claude
    Then follow Scenario A steps 3–6 if Claude shows the OAuth error.
OAuth always requires a human. The systemd services auto-restart your AI on crashes and reboots, but they cannot handle OAuth expiry. Clicking Authorize in a browser is a security requirement from Anthropic — no script can bypass it. You'll always need to SSH in and do Scenario A for OAuth issues.