VPS Setup Guide: Autonomous Agent Orchestration Stack

Deploy OmX + clawhip + oh-my-openagent on a remote server. Type in Discord from your phone. Agents build while you sleep.

What You’ll Have When Done

• A VPS running the full autonomous agent stack 24/7
• clawhip daemon auto-starting on boot, routing all events to Discord
• OmX with parallel agent teams running in persistent tmux sessions
• oh-my-openagent multi-model orchestration (Sisyphus, Hephaestus, etc.)
• Your only interface: Discord — from any device, anywhere

Before You Start

What You Need Ready

Item	Details
VPS	Ubuntu 24.04 LTS, 4+ vCPU, 8–16 GB RAM, 50+ GB SSD
SSH access	Root or sudo user
OpenAI API key	From platform.openai.com/api-keys
Anthropic API key	From console.anthropic.com (for Claude Opus as Sisyphus)
Discord bot token	You’ll create this in Step 3
Discord server	Your own server with channels you control

Recommended VPS Providers

No GPU needed — everything is API-based.

• Hetzner — Best value (€7–15/mo for 4 vCPU / 8 GB)
• DigitalOcean — $24/mo for 4 vCPU / 8 GB
• Vultr — $24/mo for 4 vCPU / 8 GB
• Contabo — Budget option, €8/mo for 6 vCPU / 16 GB

Step 1: Provision and Secure the VPS

1.1 — SSH into your fresh server

ssh root@YOUR_VPS_IP

1.2 — Create a non-root user

adduser agent
usermod -aG sudo agent

1.3 — Set up SSH key auth (from your local machine)

# On your LOCAL machine
ssh-copy-id agent@YOUR_VPS_IP

1.4 — Disable password auth (optional but recommended)

sudo nano /etc/ssh/sshd_config
# Set: PasswordAuthentication no
sudo systemctl restart sshd

1.5 — Basic firewall

sudo ufw allow OpenSSH
sudo ufw enable

1.6 — Switch to the agent user

su - agent

From here on, everything runs as the agent user.

Step 2: Install All Dependencies

2.1 — System packages

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  build-essential \
  git \
  curl \
  wget \
  tmux \
  jq \
  unzip \
  pkg-config \
  libssl-dev

2.2 — Node.js 22 (LTS)

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

# Verify
node --version   # Should show v22.x
npm --version

2.3 — Configure npm global directory

Avoid sudo for global installs.

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2.4 — Rust toolchain (for clawhip)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

# Verify
rustc --version
cargo --version

2.5 — Bun runtime (for oh-my-openagent)

curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

# Verify
bun --version

2.6 — GitHub CLI (optional)

Useful for clawhip GitHub event monitoring.

sudo apt install -y gh

Step 3: Create the Discord Bot

You need a dedicated Discord bot for clawhip. Don’t reuse existing bots — clawhip sends high-volume notifications.

3.1 — Create the bot

1. Go to https://discord.com/developers/applications
2. Click New Application → name it clawhip-agent → Create
3. Go to Bot tab in the left sidebar
4. Click Reset Token → copy and save the token securely
5. Under Privileged Gateway Intents, enable:
   • Message Content Intent
   • Server Members Intent
6. Click Save Changes

3.2 — Invite the bot to your server

1. Go to OAuth2 → URL Generator in the left sidebar
2. Check scopes: bot
3. Check bot permissions: Send Messages, Read Message History, Embed Links
4. Copy the generated URL → open it in your browser → select your server → Authorize

3.3 — Set up Discord channels

Create these channels in your server (or use existing ones):

Channel	Purpose
#agent-commands	Where you type commands for agents
#agent-status	Session updates, progress reports
#build-log	Git commits, test results
#alerts	Errors, blocks, @mentions when human input needed

3.4 — Get Channel IDs

1. In Discord: Settings → App Settings → Advanced → Enable Developer Mode
2. Right-click each channel → Copy Channel ID
3. Right-click your own name → Copy User ID

Save these — you’ll need them in Step 6.

Step 4: Set Up API Keys

4.1 — Create the environment file

nano ~/.agent-env

Paste this (fill in your actual keys):

# OpenAI
export OPENAI_API_KEY="sk-proj-..."

# Anthropic (for Claude Opus as Sisyphus orchestrator)
export ANTHROPIC_API_KEY="sk-ant-..."

# Google (optional — for Gemini workers)
export GOOGLE_API_KEY="..."

# Moonshot (optional — for Kimi K2.5, cheaper Sisyphus alternative)
export MOONSHOT_API_KEY="..."

# Exa (optional — for built-in web search MCP)
export EXA_API_KEY="..."

# Discord bot token for clawhip
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN_HERE"

4.2 — Secure the file and auto-load it

chmod 600 ~/.agent-env
echo 'source ~/.agent-env' >> ~/.bashrc
source ~/.bashrc

Step 5: Install OpenAI Codex CLI

5.1 — Install

npm install -g @openai/codex

5.2 — Authenticate (headless — pick one method)

Method A — API key (simplest, works immediately):

# Already set via ~/.agent-env, Codex will auto-detect OPENAI_API_KEY
codex --version

Note: API key auth may not give access to the newest GPT-5.3-Codex models. For those, use Method B or C.

Method B — Device code auth (gets full subscription models):

codex login --device-auth
# It will print a URL and a code
# Open the URL on your phone/laptop browser
# Enter the code and authenticate
# Return to the VPS terminal — it will confirm success

Method C — Copy auth.json from local machine:

# On your LOCAL machine (where you can open a browser):
codex login
# Complete the browser auth flow

# Then copy the auth file to the VPS:
scp ~/.codex/auth.json agent@YOUR_VPS_IP:~/.codex/auth.json

5.3 — Configure Codex

mkdir -p ~/.codex
cat > ~/.codex/config.toml << 'EOF'
model = "gpt-5.3-codex"
approval_policy = "auto-edit"

[sandbox_workspace_write]
network_access = true
EOF

5.4 — Verify

codex "echo hello from VPS"

If it responds, Codex is working.

Step 6: Install clawhip

6.1 — Install the binary

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/Yeachan-Heo/clawhip/releases/latest/download/clawhip-installer.sh | sh
source ~/.bashrc

6.2 — Configure

mkdir -p ~/.clawhip
cat > ~/.clawhip/config.toml << EOF
[providers.discord]
token = "$DISCORD_BOT_TOKEN"

# Agent session events → #agent-status
[[routes]]
event = "session.*"
sink = "discord"
channel = "PASTE_AGENT_STATUS_CHANNEL_ID"
mention = "<@PASTE_YOUR_USER_ID>"
format = "compact"
allow_dynamic_tokens = false

# Git events → #build-log
[[routes]]
event = "git.*"
sink = "discord"
channel = "PASTE_BUILD_LOG_CHANNEL_ID"
format = "compact"
allow_dynamic_tokens = false

# GitHub events → #build-log
[[routes]]
event = "github.*"
sink = "discord"
channel = "PASTE_BUILD_LOG_CHANNEL_ID"
format = "compact"
allow_dynamic_tokens = false

# Agent alerts/blocks → #alerts (with @mention)
[[routes]]
event = "agent.*"
sink = "discord"
channel = "PASTE_ALERTS_CHANNEL_ID"
mention = "<@PASTE_YOUR_USER_ID>"
format = "alert"
allow_dynamic_tokens = false
EOF

Important: Edit the file and replace all PASTE_* values with your actual Discord channel and user IDs:

nano ~/.clawhip/config.toml

6.3 — Install as systemd service (auto-start on boot)

clawhip install --systemd

6.4 — Start and verify

clawhip start
clawhip status

6.5 — Test Discord delivery

clawhip send --channel YOUR_AGENT_STATUS_CHANNEL_ID --message "clawhip is alive on VPS"

Check Discord — you should see the message appear. If it does, clawhip is working.

6.6 — Initialize memory

clawhip memory init

Step 7: Install oh-my-codex (OmX)

7.1 — Install

npm install -g oh-my-codex

7.2 — Setup and verify

omx setup
omx doctor

Fix any issues omx doctor reports before continuing.

7.3 — Set up the Discord notification skill

Inside an OmX session, you can run $configure-notifications to wire up Discord webhooks. But for the VPS, clawhip handles this externally — so OmX’s built-in Discord integration is optional.

7.4 — Quick test

# Start OmX in a tmux session
tmux new-session -s omx-test
omx
# Inside OmX, type:
# $architect "analyze this directory structure"
# Then exit: Ctrl+C, then `exit` to leave tmux

Step 8: Install oh-my-openagent (OmO)

8.1 — Install

npm install -g oh-my-opencode

8.2 — Configure

cat > ~/.config/oh-my-openagent.json << 'EOF'
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "ultrawork": {
        "model": "anthropic/claude-opus-4-6",
        "variant": "max"
      }
    },
    "hephaestus": {
      "model": "openai/gpt-5.4"
    },
    "librarian": {
      "model": "google/gemini-3-flash"
    },
    "explore": {
      "model": "google/gemini-3-flash"
    },
    "oracle": {
      "model": "openai/gpt-5.4",
      "variant": "high"
    }
  },
  "categories": {
    "quick": { "model": "openai/gpt-5-nano" },
    "unspecified-low": { "model": "anthropic/claude-sonnet-4-6" },
    "unspecified-high": { "model": "anthropic/claude-opus-4-6", "variant": "max" }
  }
}
EOF

Adjust models based on which API keys you have. If you only have OpenAI, Sisyphus can use GPT-5.4 (with the dedicated prompt path), but Claude Opus is the recommended default.

8.3 — Test

tmux new-session -s omo-test
omo
# Inside the TUI, type: ultrawork "list all files in current directory"
# Ctrl+C, exit to leave

Step 9: Create the Workspace

9.1 — Set up a projects directory

mkdir -p ~/projects
cd ~/projects

9.2 — Clone or initialize your target project

# Option A: Clone existing repo
git clone https://github.com/YOUR_USER/YOUR_REPO.git
cd YOUR_REPO

# Option B: Start fresh
mkdir my-project && cd my-project
git init

9.3 — Set up project-level agent instructions

cat > AGENTS.md << 'EOF'
# Agent Instructions

## Project Overview
[Describe your project here]

## Tech Stack
[List your technologies]

## Conventions
- Use TypeScript strict mode
- All tests must pass before committing
- Follow existing code style

## Architecture
[Describe key architectural decisions]

## What NOT to Do
- Do not modify CI/CD configuration without human approval
- Do not delete existing tests
- Do not change package versions without justification
EOF

9.4 — Set up OmX project memory

omx setup   # Run inside the project directory

This creates the .omx/ directory with project-specific memory and config.

Step 10: Wire It All Together — First Full Run

This is the moment. You’ll launch a monitored agent session and verify the complete loop.

10.1 — Make sure clawhip is running

clawhip status
# Should show: daemon running

10.2 — Start a monitored OmX session via clawhip

cd ~/projects/YOUR_REPO

clawhip tmux new -s build-session \
  --channel YOUR_AGENT_STATUS_CHANNEL_ID \
  --mention "<@YOUR_DISCORD_USER_ID>" \
  --keywords "error,complete,blocked,failed,PR created,all tests pass" \
  -- 'source ~/.bashrc && source ~/.agent-env && cd ~/projects/YOUR_REPO && omx --xhigh --madmax'

This does three things simultaneously:

1. Creates a tmux session called build-session
2. Launches OmX inside it with full power mode
3. Tells clawhip to watch the session for keywords and report to Discord

10.3 — Attach and give it a task

tmux attach -t build-session

Inside the OmX session, type:

$team 3:executor "create a basic Express.js API with health check endpoint, user CRUD routes, and Jest tests"

Watch the agents spin up. You should see:

• Worker worktrees being created in .omx/team/
• Architect analyzing the task
• Executors writing code in parallel
• Reviewer checking output

10.4 — Check Discord

Switch to your Discord server. You should see:

• Session start notification in #agent-status
• Git commit notifications in #build-log
• If anything goes wrong, alerts in #alerts

10.5 — Detach and walk away

# Press Ctrl+B, then D to detach from tmux
# The session keeps running

Now disconnect SSH entirely:

exit

The agents keep working. clawhip keeps reporting to Discord. You can check progress from your phone.

10.6 — Come back later

ssh agent@YOUR_VPS_IP
tmux attach -t build-session

Or just check Discord — if the work is done, you’ll see the completion notification.

Step 11: Automate with a Launch Script

Create a helper script so you don’t have to remember all the flags.

11.1 — Create the launcher

cat > ~/launch-agents.sh << 'SCRIPT'
#!/bin/bash
set -e

# Load environment
source ~/.bashrc
source ~/.agent-env

# Configuration
STATUS_CHANNEL="YOUR_AGENT_STATUS_CHANNEL_ID"
ALERTS_CHANNEL="YOUR_ALERTS_CHANNEL_ID"
USER_MENTION="<@YOUR_DISCORD_USER_ID>"
KEYWORDS="error,complete,blocked,failed,all tests pass,PR created"

# Check clawhip
if ! clawhip status > /dev/null 2>&1; then
  echo "Starting clawhip..."
  clawhip start
  sleep 2
fi

# Get project and session name
PROJECT_DIR="${1:-.}"
SESSION_NAME="${2:-agent-$(date +%H%M)}"

cd "$PROJECT_DIR"
PROJECT_NAME=$(basename "$(pwd)")

echo "Launching agent session: $SESSION_NAME"
echo "Project: $PROJECT_NAME"
echo "Directory: $(pwd)"

# Notify Discord
clawhip send --channel "$STATUS_CHANNEL" \
  --message "Agent session **$SESSION_NAME** starting for **$PROJECT_NAME** $USER_MENTION"

# Launch monitored session
clawhip tmux new -s "$SESSION_NAME" \
  --channel "$STATUS_CHANNEL" \
  --mention "$USER_MENTION" \
  --keywords "$KEYWORDS" \
  -- "source ~/.bashrc && source ~/.agent-env && cd $(pwd) && omx --xhigh --madmax"

SCRIPT

chmod +x ~/launch-agents.sh

11.2 — Edit with your actual IDs

nano ~/launch-agents.sh
# Replace YOUR_AGENT_STATUS_CHANNEL_ID, YOUR_ALERTS_CHANNEL_ID, YOUR_DISCORD_USER_ID

11.3 — Usage

# Launch agents for a specific project
~/launch-agents.sh ~/projects/my-app session-name

# Launch agents for current directory
cd ~/projects/my-app
~/launch-agents.sh

Step 12: Session Management Cheat Sheet

tmux commands (manage agent sessions)

# List all running sessions
tmux ls

# Attach to a session
tmux attach -t session-name

# Detach (keep running): Ctrl+B, then D

# Kill a specific session
tmux kill-session -t session-name

# Kill all sessions
tmux kill-server

clawhip commands (monitor and notify)

# Check daemon status
clawhip status

# List watched tmux sessions
clawhip tmux list

# Send manual notification
clawhip send --channel CHANNEL_ID --message "your message"

# Restart daemon
clawhip update --restart

# View logs
journalctl --user -u clawhip -f

OmX commands (inside an agent session)

# Parallel team execution
$team 3:executor "your task description"

# Persistent single-agent loop
$ralph "carry this to completion"

# Plan first, then execute
$deep-interview "clarify requirements"
$ralplan "approve the plan"
$team 3:executor "execute the approved plan"

# Check status
$hud

# Cancel current execution
$cancel

oh-my-openagent commands

# Launch TUI
omo

# Inside TUI: full auto mode
ultrawork "your task"

# Or shorter
ulw "your task"

# Enter planner mode: press Tab
# Then: /start-work to execute the plan

Maintenance

Keep tools updated

# Codex CLI
npm update -g @openai/codex

# OmX
npm update -g oh-my-codex
omx setup   # Re-run after updates

# clawhip
clawhip update --restart

# oh-my-openagent
npm update -g oh-my-opencode

Monitor resource usage

# Check memory (parallel agents can be hungry)
free -h

# Check disk (git worktrees add up)
df -h

# Check running processes
htop

Clean up old worktrees

# Inside a project directory
cd ~/projects/YOUR_REPO
rm -rf .omx/team/*/worktrees/*
git worktree prune

Rotate API keys

Update ~/.agent-env with new keys, then:

source ~/.agent-env

# Restart any active tmux sessions to pick up new keys
tmux kill-server
# Re-launch with ~/launch-agents.sh

Troubleshooting

Problem	Fix
omx: command not found	Run source ~/.bashrc, check ~/.npm-global/bin is in PATH
clawhip start fails	Check ~/.clawhip/config.toml for valid bot token
Discord bot doesn’t post	Verify bot has Send Messages permission in the channel
Codex auth expired	Re-run codex login --device-auth or copy fresh auth.json
Agents run out of context	clawhip should handle monitoring; check .omx/ config
tmux session died	Check tmux ls; restart with ~/launch-agents.sh
High memory usage	Reduce $team worker count (use $team 2:executor instead of 3)
Git conflicts in worktrees	Check .omx/team/integration-report.md for details
clawhip not starting on boot	Re-run clawhip install --systemd
OmX doctor reports issues	Run omx doctor and follow its suggestions
omo command not found	Try oh-my-opencode or re-install with npm i -g oh-my-opencode

Security Notes

• Never commit ~/.agent-env to git. It contains all your API keys.
• API keys are sent to provider APIs (OpenAI, Anthropic, etc.) — agents use these to make inference calls. The code stays on your VPS; only prompts and responses travel to the APIs.
• Codex runs commands on your VPS. In --full-auto / --madmax mode, agents can execute arbitrary shell commands. This is the intended behavior, but be aware of it.
• Git push permissions. If agents have write access to your GitHub repos, they can push commits. Consider using a separate GitHub deploy key with limited permissions.
• Firewall. Keep your VPS firewall tight — only SSH inbound. All agent traffic is outbound API calls.

---

Guide compiled April 4, 2026. Tools are actively developed — check GitHub repos for breaking changes before updating.