Each agent runs their own docsify web server for immediate workspace file access. Auto-starts with systemd.
SKILL.md

---
name: agent-webservers
description: Each agent runs their own docsify web server for immediate workspace file access. Auto-starts with systemd.
---

# Agent Web Servers

Each agent runs a docsify web server to serve their workspace files for immediate access via web links.

## URLs

| Agent | URL | Workspace | Service |
|-------|-----|-----------|---------|
| **Ada** 🔮 | http://100.106.69.9:8788 | ~/clawd/ | ada-webserver.service |
| **Spock** 🖖 | http://100.106.69.9:8789 | ~/clawd-spock/ | spock-webserver.service |
| **Scotty** 🔧 | http://100.68.207.75:8788 | ~/clawd/ | scotty-webserver.service |

**Obsidian Vault** (Mac, when on): http://100.86.150.96:8787/#/

---

## Architecture

### Why Each Agent Has Own Server
1. **Always accessible** - No dependency on Mac being on
2. **Immediate links** - Files accessible right after agent creates them
3. **Independent** - Each agent owns their data
4. **Syncs to vault** - Obsidian vault = master collection for Henry

### Sync Flow
```
Agent creates file in workspace
    ↓
Immediately accessible via agent's web server
    ↓
Syncs to Obsidian vault (when Mac is on)
    ↓
Henry views in Obsidian app (unified view)
```

---

## Link Formats

### Agent Workspace Files
**Format:** `http://[server]:port/[relative-path].md`

**Examples:**
- Ada's memory: http://100.106.69.9:8788/memory.md
- Ada's roadmap: http://100.106.69.9:8788/memory/roadmap.md
- Spock's research: http://100.106.69.9:8789/memory/flight-search-research.md
- Scotty's config: http://100.68.207.75:8788/memory.md

### Obsidian Vault (Mac)
**Format:** `http://100.86.150.96:8787/#/[folder]/[filename]` (no .md extension)

**Examples:**
- http://100.86.150.96:8787/#/Ada/clawdbot-skills-inventory
- http://100.86.150.96:8787/#/Curacel/AI-Sales-Stack-QuickStart

---

## Service Management

### Check Status
```bash
# Ada + Spock (ada-gateway)
sudo systemctl status ada-webserver spock-webserver

# Scotty (Pi)
ssh jamify@100.68.207.75 "sudo systemctl status scotty-webserver"
```

### Restart
```bash
# Ada
sudo systemctl restart ada-webserver

# Spock
sudo systemctl restart spock-webserver

# Scotty
ssh jamify@100.68.207.75 "sudo systemctl restart scotty-webserver"
```

### View Logs
```bash
# Ada
sudo journalctl -u ada-webserver -f

# Spock
sudo journalctl -u spock-webserver -f

# Scotty
ssh jamify@100.68.207.75 "sudo journalctl -u scotty-webserver -f"
```

---

## Setup (Already Done)

### Per Agent

1. **Create index.html** in workspace root:
```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>[Agent] Workspace</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/dark.css">
</head>
<body>
  <div id="app">Loading...</div>
  <script>
    window.$docsify = {
      name: '[Agent] Workspace',
      loadSidebar: false,
      subMaxLevel: 3,
      search: {
        paths: 'auto',
        placeholder: 'Search',
        noData: 'No results'
      }
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>
</html>
```

2. **Create systemd service** at `/etc/systemd/system/[agent]-webserver.service`:
```ini
[Unit]
Description=[Agent] Workspace Web Server
After=network.target clawdbot.service

[Service]
Type=simple
User=[user]
WorkingDirectory=[workspace-path]
ExecStart=/usr/bin/python3 -m http.server [port]
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

3. **Enable and start**:
```bash
sudo systemctl daemon-reload
sudo systemctl enable [agent]-webserver
sudo systemctl start [agent]-webserver
```

---

## Ports

| Port | Agent | Machine |
|------|-------|---------|
| 8788 | Ada | ada-gateway |
| 8789 | Spock | ada-gateway |
| 8788 | Scotty | Pi (100.68.207.75) |
| 8787 | Obsidian Vault | Mac (100.86.150.96) |

---

## When to Use Each

### Agent Workspace Links
**Use when:**
- Agent just created/updated a file
- Need immediate access (Mac might be off)
- Linking to agent-specific files (memory, research, output)

**Example:** "Saved research to: http://100.106.69.9:8789/memory/curacel-ai-sales-stack.md"

### Obsidian Vault Links
**Use when:**
- File has been synced to vault
- Linking to unified/master collection
- Mac is known to be on
- File is in Obsidian-specific folders (Ada/, DailyBriefs/, etc.)

**Example:** "Saved to vault: http://100.86.150.96:8787/#/Ada/clawdbot-skills-inventory"

---

## Troubleshooting

### Server Not Responding
```bash
# Check if process is running
sudo systemctl status [agent]-webserver

# Check if port is listening
lsof -i :[port]

# Restart
sudo systemctl restart [agent]-webserver
```

### 404 Errors
- Check file exists: `ls -la ~/clawd/[path]`
- Check index.html exists in workspace root
- Verify URL format (include .md extension for direct files)

### Port Conflicts
```bash
# Check what's using the port
lsof -i :8788

# Kill conflicting process
sudo kill [PID]

# Restart service
sudo systemctl restart [agent]-webserver
```

---

## Implementation Date
**2026-01-18**

Implemented by Ada at Henry's request. All agents now have their own always-on web servers for immediate file access.
Agent Web Servers

SKILL.md

related skills
