VPS Setup Guide

Run Agent Second Brain 24/7 on a virtual private server.

Requirements

• VPS with Ubuntu 22.04+ (minimum 1GB RAM, recommended 2GB)
• Root or sudo access
• SSH client

Recommended VPS Providers

Provider	Price	Region
Contabo	from $5/mo	Europe
Hetzner	from $4/mo	Europe
DigitalOcean	from $6/mo	Global
Vultr	from $5/mo	Global

---

Step 1: Connect to Server

After purchasing VPS, you'll get:

• IP address (e.g., 162.55.123.45)
• Root password

Connect via SSH:

ssh root@162.55.123.45

Enter password (characters won't display — that's normal).

---

Step 2: Create User

Never work as root. Create a regular user:

# Create user (replace "myuser" with your name)
adduser myuser

# Follow prompts:
# - Enter password (twice)
# - Other fields can be skipped (Enter)

# Grant sudo rights
usermod -aG sudo myuser

# Switch to new user
su - myuser

---

Step 3: Update System

sudo apt update && sudo apt upgrade -y

---

Step 4: Install Base Tools

# Git
sudo apt install -y git

# Curl and wget
sudo apt install -y curl wget

# Build tools
sudo apt install -y build-essential

# Verify
git --version

---

Step 5: Install Python 3.12

sudo apt install -y software-properties-common
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.12 python3.12-venv python3.12-dev

# Verify
python3.12 --version

---

Step 6: Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# Verify
uv --version

---

Step 7: Install Node.js

Required for Claude Code:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verify
node --version
npm --version

---

Step 8: Install Claude CLI

npm install -g @anthropic-ai/claude-code

# Verify
which claude
claude --version

# Authenticate
claude auth login

After claude auth login:

1. A URL appears
2. Copy and open it in browser on your computer
3. Log in to Anthropic account
4. Authorize access
5. Return to terminal — it will confirm

---

Step 9: Clone Project

cd ~
mkdir -p projects
cd projects

git clone https://github.com/smixs/agent-second-brain.git
cd agent-second-brain

ls -la

---

Step 10: Install Dependencies

uv sync

# Verify
uv run python -c "import aiogram; print('aiogram OK')"

---

Step 11: Get Tokens

Telegram Bot Token

1. Open Telegram
2. Find @BotFather
3. Send /newbot
4. Enter bot name and username
5. Copy the token

Your Telegram User ID

1. Find @userinfobot in Telegram
2. Send any message
3. Copy the ID number

Deepgram API Key

1. Go to https://console.deepgram.com/
2. Sign up (free $200 credit)
3. Settings → API Keys
4. Create key and copy

Step 12: Configure Environment

nano ~/projects/agent-second-brain/.env

Paste (replace with your values):

TELEGRAM_BOT_TOKEN=7123456789:AAHdN8J2K4m5N6o7P8q9R0s1T2u3V4w5X6y
DEEPGRAM_API_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
VAULT_PATH=./vault
ALLOWED_USER_IDS=[123456789]

Save: Ctrl+O, Enter, Ctrl+X

---

Step 13: Clean Vault Examples

cd ~/projects/agent-second-brain

rm -rf vault/daily/*
rm -rf vault/thoughts/ideas/*
rm -rf vault/thoughts/projects/*
rm -rf vault/thoughts/learnings/*
rm -rf vault/thoughts/reflections/*
rm -rf vault/summaries/*
rm -rf vault/attachments/*

---

Step 14: Customize Goals

Edit goals to match yours:

nano vault/goals/0-vision-3y.md    # 3-year vision
nano vault/goals/1-yearly-2026.md  # Yearly goals
nano vault/goals/2-monthly.md      # Monthly priorities
nano vault/goals/3-weekly.md       # Weekly focus

---

Step 15: Test Run

cd ~/projects/agent-second-brain
uv run python -m d_brain

Should show:

INFO:aiogram.dispatcher:Start polling
INFO:aiogram.dispatcher:Run polling for bot @your_bot_name

Test in Telegram:

• Find your bot
• Send /start
• Send a voice message

Stop with Ctrl+C.

---

Step 16: Install Services (one command)

All services — the bot, the persistent brain session, the watchdog, the daily processing timer and the health-check timer — are installed by one idempotent script:

cd ~/projects/agent-second-brain
bash upgrade.sh

It installs tmux, syncs Python dependencies, installs the dbrain CLI, sets up dbrain-* systemd --user units (no root services), enables linger so everything survives reboots, and runs a first health check.

Check:

dbrain status
systemctl --user is-active dbrain-bot dbrain-watchdog dbrain-process.timer dbrain-doctor.timer

---

Step 17: Git Configuration

cd ~/projects/agent-second-brain

git config user.email "your@email.com"
git config user.name "Your Name"

Create your own repository

1. GitHub → "+" → "New repository"
2. Name: my-second-brain
3. Leave empty (no README)
4. Create

Change remote

git remote set-url origin https://github.com/YOUR_USERNAME/my-second-brain.git
git remote -v
git push -u origin main

If prompted for password, use Personal Access Token:

• GitHub → Settings → Developer settings → Personal access tokens

---

Useful Commands

# Bot status
dbrain status

# Restart bot (the brain session survives — KillMode=process)
systemctl --user restart dbrain-bot

# Stop bot
systemctl --user stop dbrain-bot

# Real-time logs
journalctl --user -u dbrain-bot -f

# Last 100 log lines
journalctl --user -u dbrain-bot -n 100

# All dbrain services
systemctl --user status 'dbrain-*'

# List timers
systemctl --user list-timers

# Manual processing
cd ~/projects/agent-second-brain
./scripts/process.sh

# Update code
cd ~/projects/agent-second-brain
bash upgrade.sh

---

Troubleshooting

Bot doesn't respond

dbrain status
journalctl --user -u dbrain-bot -n 100
cat ~/projects/agent-second-brain/.env | grep TELEGRAM_BOT_TOKEN
systemctl --user restart dbrain-bot

Voice not transcribing

cat ~/projects/agent-second-brain/.env | grep DEEPGRAM
journalctl --user -u dbrain-bot | grep -i error

Processing errors

claude --version
claude auth status
claude auth login  # if needed

Permission errors

sudo chown -R myuser:myuser ~/projects/agent-second-brain
chmod -R 755 ~/projects/agent-second-brain

Git push fails

git remote -v
git status
git config --global credential.helper store
git push

---

Sync with Local Computer

See main README for Obsidian sync options.

---

Security Tips

• Use SSH keys instead of passwords
• Keep system updated: sudo apt update && sudo apt upgrade
• .env is in .gitignore — never commit tokens
• Consider setting up firewall: sudo ufw enable