> ## Documentation Index
> Fetch the complete documentation index at: https://superturtle.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Running as a Service

> Keep the bot running 24/7 on macOS or Linux

## Default: superturtle start (tmux)

The simplest way to run the bot persistently:

```bash theme={null}
superturtle start
```

This creates a project-scoped tmux session that survives terminal disconnects.

```bash theme={null}
superturtle status          # Check if running
superturtle stop            # Stop the bot
superturtle start           # Re-attach to the running tmux session
```

<Info>
  For most users, `superturtle start` is all you need. Use `superturtle status` to print the exact tmux session and log paths for the current project. The sections below are for production setups that need auto-start on boot and crash recovery.
</Info>

## macOS (LaunchAgent)

For auto-start on boot and automatic restart on crash.

### Setup

1. Copy the template:

```bash theme={null}
cp super_turtle/claude-telegram-bot/launchagent/com.claude-telegram-ts.plist.template \
   ~/Library/LaunchAgents/com.claude-telegram-ts.plist
```

2. Edit the plist:

```bash theme={null}
nano ~/Library/LaunchAgents/com.claude-telegram-ts.plist
```

Set your paths and credentials:

```xml theme={null}
<key>TELEGRAM_BOT_TOKEN</key>
<string>your-bot-token</string>

<key>TELEGRAM_ALLOWED_USERS</key>
<string>your-telegram-user-id</string>

<key>CLAUDE_WORKING_DIR</key>
<string>/Users/YOUR_USERNAME/path/to/project</string>

<key>PATH</key>
<string>/Users/YOUR_USERNAME/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
```

3. Load and verify:

```bash theme={null}
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-telegram-ts.plist
launchctl list | grep com.claude-telegram-ts
```

### Managing

```bash theme={null}
launchctl bootout gui/$(id -u)/com.claude-telegram-ts              # Stop
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-telegram-ts.plist  # Start
launchctl kickstart -k gui/$(id -u)/com.claude-telegram-ts         # Restart
```

### Prevent sleep

Go to **System Settings > Battery > Options** and enable **"Prevent automatic sleeping when the display is off"** (on power adapter).

### Shell aliases

```bash theme={null}
alias st='launchctl list | grep com.claude-telegram-ts'
alias st-stop='launchctl bootout gui/$(id -u)/com.claude-telegram-ts 2>/dev/null && echo "Stopped"'
alias st-start='launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-telegram-ts.plist 2>/dev/null && echo "Started"'
alias st-restart='launchctl kickstart -k gui/$(id -u)/com.claude-telegram-ts && echo "Restarted"'
```

## Linux (systemd)

### Setup

1. Copy the template:

```bash theme={null}
mkdir -p ~/.config/systemd/user
cp super_turtle/claude-telegram-bot/systemd/superturtle-bot.service.template \
   ~/.config/systemd/user/superturtle-bot.service
```

2. Edit with your paths:

```bash theme={null}
nano ~/.config/systemd/user/superturtle-bot.service
```

```ini theme={null}
WorkingDirectory=/home/USERNAME/superturtle
ExecStart=/bin/bash -lc 'cd /home/USERNAME/superturtle && exec "${SUPERTURTLE_BIN:-superturtle}" service run'

Environment=TELEGRAM_BOT_TOKEN=your-bot-token
Environment=TELEGRAM_ALLOWED_USERS=123456789
Environment=CLAUDE_WORKING_DIR=/home/USERNAME/superturtle
Environment=SUPERTURTLE_BIN=superturtle
```

3. Enable and start:

```bash theme={null}
systemctl --user daemon-reload
systemctl --user enable --now superturtle-bot
systemctl --user status superturtle-bot
```

### Managing

```bash theme={null}
systemctl --user stop superturtle-bot
systemctl --user start superturtle-bot
systemctl --user restart superturtle-bot
```

### Logs

```bash theme={null}
journalctl --user -u superturtle-bot -f         # Follow
journalctl --user -u superturtle-bot -n 50       # Last 50 lines
journalctl --user -u superturtle-bot --since="1 hour ago"
```

### Shell aliases

```bash theme={null}
alias st='systemctl --user status superturtle-bot'
alias st-stop='systemctl --user stop superturtle-bot'
alias st-start='systemctl --user start superturtle-bot'
alias st-restart='systemctl --user restart superturtle-bot'
alias st-logs='journalctl --user -u superturtle-bot -f'
```

## Development mode

For contributors working on superturtle itself:

```bash theme={null}
cd super_turtle/claude-telegram-bot
bun run dev    # Auto-reload on file changes
```

## Troubleshooting

### Bot doesn't start

```bash theme={null}
# tmux mode
superturtle status               # Prints exact tmux attach + log paths

# macOS LaunchAgent
superturtle logs loop

# Linux systemd
journalctl --user -u superturtle-bot -f
```

Common issues: invalid bot token, missing bun binary, working directory doesn't exist.

### Bot keeps restarting

Check logs for crash reasons: Claude Code auth failure, network issues, Telegram rate limit, OOM.

### Telegram not receiving messages

* Verify bot token (`/start` in Telegram)
* Check user ID is in `TELEGRAM_ALLOWED_USERS`
* Check network connectivity

## Platform differences

| Feature             | macOS                      | Linux                      |
| ------------------- | -------------------------- | -------------------------- |
| **Default**         | `superturtle start` (tmux) | `superturtle start` (tmux) |
| **Service manager** | launchd                    | systemd                    |
| **Auto-start**      | `RunAtLoad=true`           | `WantedBy=default.target`  |

## Next steps

* [Personal Assistant](/bot/personal-assistant) — Set up Claude as your assistant
* [Environment Variables](/config/environment-variables) — Full config reference
* [Security](/config/security) — Permissions and safety