YOUR BRAND
[Your AI Name] Guardian
Your AI management console — monitor, restart, and connect with one word
Template — Customize for Your AI
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
-
1Open Terminal on your Mac and connectSSH 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. -
2Check for active tmux sessions
tmux list-sessions
-
3Read the resultHealthy — sessions exist
56: 1 windows (created ...) yourai-unified: 1 windows ...
Unhealthy — no sessionsno 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 namedyourai-recovery-YYYYMMDD-HHMM. -
4Optional deeper check — systemd service statusCheck all AI services
systemctl status yourai-session.service --no-pager systemctl status yourai-telegram.service --no-pager
Both should showactive (running). If either showsfailed, restart it (see Section 4). -
5Disconnect when done
exit
2. Live Monitoring
Watch exactly what [Your AI Name] is doing in real time
-
1SSH in and list sessions
ssh tmux list-sessions
-
2Attach 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 withCtrl+B [then arrow keys. Pressqto exit scroll mode. -
3Detach safely without disturbing your AISafe 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. -
4Read-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
-
1One-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'
-
2Or restart manually from inside the serverSSH in
ssh
Run the restart scriptbash /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. -
3Wait for confirmation messageThe 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.
-
4Verify it is backConfirm new session exists
tmux list-sessions
You should see a session namedyourai-recovery-YYYYMMDD-HHMM. That is your AI's fresh start. -
5Disconnect
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.
| Service | What It Does |
|---|---|
| yourai-session.service | Keeps Claude Code + messaging bridge always running |
| yourai-telegram.service | Messaging bridge (2-way messaging with [Your Name]) |
| yourai-portal.service | Portal UI (port YOUR_PORT) |
| yourai-logserver.service | Web conversation logging (port YOUR_PORT) |
| yourai-comms-gateway.service | Communications 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 IP | YOUR.SERVER.IP |
| SSH user | youruser |
| SSH port | 22 (standard) |
| Project root | /home/youruser/your-ai-project |
| Restart script | tools/yourai-restart.sh |
| Messaging bridge | tools/messaging_bridge.py |
| Session name after restart | yourai-recovery-YYYYMMDD-HHMM |
| Messaging bridge log | logs/messaging_bridge.log |
| Session manager log | logs/session_manager.log |
| Detach from tmux | Ctrl+B then D |
| Read-only snapshot | tmux 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.
-
1Check if you already have an SSH key on your MacMac 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. -
2Generate 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). -
3Copy your public key to the serverRun 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. -
4Add a one-word Terminal shortcutAdd 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 typemyaiin Terminal — it SSHs in and drops you directly into the live AI session. Same session as the portal. One word, instant connection. Theconnect-yourai.shscript reads.current_sessionso 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.
-
1What 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)
-
2Ask your AI to create the server-side connect scriptTell 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 fiYour AI also needs to make it executable:chmod +x connect-ai.shImportant: Your AI's startup/restart script must write the current tmux session name to.current_sessionevery time it starts. Example:echo "$(tmux display-message -p '#{session_name}')" > .current_session -
3Run this ONE-TIME setup script on your MacCopy the script below. Save it as
setup-myai.shon your Mac. Open Terminal and run:bash setup-myai.shIt 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 "" -
4Test itClose 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, pressCtrl+BthenD(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.-
1SSH in, then make sure you are the correct usertmux 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 arewhoami # If it says "root", switch to your user: su - youruser
-
2Attach to the running tmux sessionFind and attach to the session
tmux list-sessions tmux attach
You'll see Claude Code showing the OAuth error. That's expected. -
3Exit Claude Code first (critical)You cannot run
claude loginfrom inside Claude Code. Exit it first.Stop Claude CodeCtrl+C # If the prompt doesn't return, try: /exit or press q
You should now see a plain bash prompt. -
4Run
claude loginFrom the bash promptclaude login
Claude Code will output a URL. Copy that entire URL. -
5Open the URL in your browser and authorizePaste 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.
-
6Start Claude Code fresh, then detachRestart 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: pressCtrl+BthenD.
SCENARIO B
Claude Code Not Found / PATH Issue
Symptom:
claude: command not found when you try to run claude or claude login.-
1Check 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 PATHexport PATH="$HOME/.local/bin:$PATH" echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
-
2If not installed, reinstall Claude CodeReinstall + 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 claudeshould 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.
-
1Check bridge statusCheck Telegram bridge service
systemctl --user status yourai-telegram.service --no-pager journalctl --user -u yourai-telegram.service --no-pager -n 20
-
2Kill and restart manuallyManual 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 systemdsystemctl --user restart yourai-telegram.service
-
3Verify the bridge is workingWatch 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.
-
1SSH in as your user (switch from root if needed)
ssh # If you land as root: su - youruser
-
2Kill everythingNuclear kill sequence
tmux kill-server pkill -f telegram_bridge.py pkill -f claude
-
3Clean up stale lock files
cd /home/youruser/your-ai-project rm -f .telegram_bridge.pid .current_session .agentmail_monitor.pid .boop_executor.pid
-
4Restart via systemd and wait
sudo systemctl restart yourai-session.service sleep 30 tmux list-sessions
If a session appears, runtmux attach. If Claude Code shows an OAuth error, follow Scenario A steps 3–6 to reauthorize. -
5If no session was created, start one manuallyManual 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.