Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Self-Hosted Agent Server

agentful isn't just a toolkit - it's a self-hosted AI agent orchestration server that runs on YOUR infrastructure.

What is agentful serve?

The agentful serve command transforms your server into an autonomous agent execution platform:

# Deploy on your infrastructure
agentful serve --auth=tailscale --port=3000
 
# Now accessible remotely
curl -X POST https://your-server:3000/agent/orchestrator \
  -H "Content-Type: application/json" \
  -d '{"task": "Build authentication system"}'

Key Features:

  • 🔒 Self-hosted: Your code never leaves your infrastructure
  • 🌐 Remote execution: Run agents from anywhere (CI/CD, mobile, web)
  • 🔐 Multiple auth modes: Tailscale, HMAC, SSH tunnels
  • 🚀 Multi-platform CI/CD: GitHub Actions, GitLab, Jenkins, CircleCI
  • 💰 Cost-effective: Deploy on Oracle Cloud free tier ($0/month)

Why Self-Host?

Data Privacy & Control

Your Code Stays on Your Servers:

# Traditional Claude Code
Local Machine → Anthropic API → Response
(Code sent to Anthropic)
 
# agentful serve
CI/CD → Your Server → LLM API → Your Server → Response
(Code never leaves your infrastructure)

Benefits:

  • Proprietary code never transmitted
  • Compliance (SOC 2, HIPAA, GDPR)
  • Air-gapped deployments possible
  • Full audit trail

Cost Optimization

Oracle Cloud Free Tier (Forever Free):

  • 4 ARM cores (Ampere A1)
  • 24GB RAM
  • 200GB storage
  • $0/month

vs Managed Services:

  • Replit Agents: $25-100/month
  • GitHub Copilot Enterprise: $39/user/month
  • Cursor Pro: $20/month

Break-even: ~5-10 users on self-hosted

Multi-Platform CI/CD

Not Locked to GitHub Actions:

# GitHub Actions
- uses: your-server:3000/agent/architect
 
# GitLab CI
script:
  - curl https://your-server:3000/agent/backend
 
# Jenkins
sh 'curl https://your-server:3000/agent/tester'
 
# CircleCI, Bitbucket, Travis, etc.
# Standard HTTP API works everywhere

Remote Development

Mobile-First Future:

# Future: Voice interface on mobile
Phone → "Build me a todo app"
      → agentful server
      → Agents build entire app
      → Return working app
 
# Voice → Autonomous Agents → Deployed App

Architecture

Server Components

┌─────────────────────────────────────────────┐
│         agentful Server Architecture        │
├─────────────────────────────────────────────┤
│                                             │
│  ┌───────────────────────────────────────┐ │
│  │     HTTP/REST API (Port 3000)         │ │
│  │  POST /agent/{name}                   │ │
│  │  GET /status                          │ │
│  │  POST /pipeline/execute               │ │
│  └───────────────────────────────────────┘ │
│                    ↓                        │
│  ┌───────────────────────────────────────┐ │
│  │     Authentication Layer              │ │
│  │  • Tailscale (recommended)            │ │
│  │  • HMAC signatures                    │ │
│  │  • SSH tunnel                         │ │
│  └───────────────────────────────────────┘ │
│                    ↓                        │
│  ┌───────────────────────────────────────┐ │
│  │     Agent Orchestrator                │ │
│  │  Routes to specialized agents         │ │
│  └───────────────────────────────────────┘ │
│                    ↓                        │
│  ┌───────────────────────────────────────┐ │
│  │     8 Specialized Agents              │ │
│  │  orchestrator │ architect │ backend   │ │
│  │  frontend │ tester │ reviewer │ fixer │ │
│  └───────────────────────────────────────┘ │
│                    ↓                        │
│  ┌───────────────────────────────────────┐ │
│  │     LLM Provider (configurable)       │ │
│  │  Claude │ GLM │ DeepSeek │ Gemini    │ │
│  └───────────────────────────────────────┘ │
│                    ↓                        │
│  ┌───────────────────────────────────────┐ │
│  │     Quality Gates & Validation        │ │
│  │  Types │ Lint │ Tests │ Coverage      │ │
│  └───────────────────────────────────────┘ │
│                                             │
└─────────────────────────────────────────────┘

Request Flow

1. Client Request
   ↓
2. Authentication (Tailscale/HMAC/SSH)
   ↓
3. Route to Agent
   ↓
4. Agent Execution (with LLM)
   ↓
5. Quality Gates
   ↓
6. Return Results

Deployment Options

Oracle Cloud (Recommended - Free Forever)

Why Oracle Cloud Free Tier?:

  • Always free: No time limit, no credit card charges
  • Powerful: 4 ARM cores, 24GB RAM
  • Global: Data centers worldwide
  • Stable: Enterprise-grade infrastructure

Setup:

# 1. Create Oracle Cloud account
# 2. Launch Always Free ARM instance (Ubuntu)
# 3. Install Node.js 22+
# 4. Deploy agentful
 
ssh ubuntu@your-oracle-instance
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @itz4blitz/agentful
agentful serve --auth=tailscale --port=3000

Full Oracle Cloud Guide →

AWS / GCP / Azure

For existing infrastructure:

# AWS EC2 (t3.medium recommended)
aws ec2 run-instances \
  --image-id ami-xxx \
  --instance-type t3.medium \
  --user-data "#!/bin/bash
    npm install -g @itz4blitz/agentful
    agentful serve --auth=hmac"
 
# GCP Compute Engine
gcloud compute instances create agentful-server \
  --machine-type=e2-medium \
  --startup-script="npm install -g @itz4blitz/agentful && agentful serve"
 
# Azure VM
az vm create \
  --resource-group myResourceGroup \
  --name agentful-server \
  --custom-data cloud-init.txt

Full Cloud Provider Guide →

Docker / Kubernetes

Containerized deployment:

FROM node:22-alpine
RUN npm install -g @itz4blitz/agentful
EXPOSE 3000
CMD ["agentful", "serve", "--port=3000"]
# kubernetes deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: agentful-server
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: agentful
        image: agentful:latest
        ports:
        - containerPort: 3000

Full Docker/K8s Guide →

On-Premises / Homelab

Self-hosted on your hardware:

# Ubuntu server
sudo apt update
sudo apt install nodejs npm
npm install -g @itz4blitz/agentful
 
# Start with systemd
sudo systemctl enable agentful
sudo systemctl start agentful

Full On-Prem Guide →

Authentication Modes

Tailscale (Recommended)

Zero-config VPN with WireGuard:

# Install Tailscale on server
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
 
# Start agentful with Tailscale auth
agentful serve --auth=tailscale --port=3000
 
# Access from any Tailscale device
curl http://your-server-name:3000/agent/orchestrator

Benefits:

  • ✅ Encrypted by default (WireGuard)
  • ✅ No exposed ports
  • ✅ Automatic DNS
  • ✅ ACLs for access control
  • ✅ Works across NAT/firewalls

Tailscale Setup Guide →

HMAC Signatures

Public endpoints with request signing:

# Generate secret
export AGENTFUL_SECRET=$(openssl rand -base64 32)
 
# Start server
agentful serve --auth=hmac --secret=$AGENTFUL_SECRET
 
# Client signs requests
SIGNATURE=$(echo -n "$REQUEST_BODY" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)
 
curl -X POST https://your-server:3000/agent/orchestrator \
  -H "X-Agentful-Signature: $SIGNATURE" \
  -H "X-Agentful-Timestamp: $(date +%s)" \
  -d "$REQUEST_BODY"

Features:

  • ✅ Replay attack protection (timestamp validation)
  • ✅ Request integrity (tamper-proof)
  • ✅ Works with public endpoints
  • ✅ No VPN required

HMAC Setup Guide →

SSH Tunnel

Localhost-only with SSH port forwarding:

# Server (no auth needed, listens on localhost only)
agentful serve --auth=none --host=127.0.0.1 --port=3000
 
# Client (create SSH tunnel)
ssh -L 3000:localhost:3000 your-server
 
# Access via localhost
curl http://localhost:3000/agent/orchestrator

Best For:

  • Development environments
  • Temporary access
  • Simple setups

SSH Tunnel Guide →

API Reference

POST /agent/{agent_name}

Execute a specific agent:

curl -X POST https://your-server:3000/agent/architect \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Design authentication system",
    "context": {
      "project": "/path/to/project",
      "stack": ["node", "react", "postgres"]
    }
  }'

Available Agents:

  • orchestrator - Overall task coordination
  • architect - System design
  • backend - Server-side implementation
  • frontend - Client-side implementation
  • tester - Test generation and execution
  • reviewer - Code review
  • fixer - Bug fixing
  • product-analyzer - Product spec analysis

POST /pipeline/execute

Execute multi-agent pipeline:

curl -X POST https://your-server:3000/pipeline/execute \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {"agent": "architect", "task": "Design system"},
      {"agent": "backend", "task": "Implement API"},
      {"agent": "frontend", "task": "Build UI"},
      {"agent": "tester", "task": "Generate tests"},
      {"agent": "reviewer", "task": "Review code"}
    ],
    "context": {
      "project_root": "/workspace"
    }
  }'

GET /status

Health check:

curl https://your-server:3000/status
 
# Response:
{
  "status": "healthy",
  "uptime": 86400,
  "agents": 8,
  "llm_provider": "glm-4.7",
  "version": "1.1.0"
}

Full API Documentation →

CI/CD Integration

GitHub Actions

name: agentful CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Run agentful architect
        run: |
          curl -X POST ${{ secrets.AGENTFUL_SERVER }}/agent/architect \
            -H "X-Agentful-Signature: ${{ secrets.AGENTFUL_SIGNATURE }}" \
            -d '{"prompt": "Review architecture"}'
 
      - name: Run agentful tester
        run: |
          curl -X POST ${{ secrets.AGENTFUL_SERVER }}/agent/tester \
            -d '{"prompt": "Generate integration tests"}'

GitLab CI

stages:
  - analyze
  - test
 
architect:
  stage: analyze
  script:
    - curl -X POST $AGENTFUL_SERVER/agent/architect
          -d '{"prompt": "Analyze changes"}'
 
tester:
  stage: test
  script:
    - curl -X POST $AGENTFUL_SERVER/agent/tester
          -d '{"prompt": "Run tests"}'

Jenkins

pipeline {
  agent any
  stages {
    stage('agentful Review') {
      steps {
        sh '''
          curl -X POST ${AGENTFUL_SERVER}/agent/reviewer \
            -d '{"prompt": "Review PR changes"}'
        '''
      }
    }
  }
}

Full CI/CD Integration Guide →

Monitoring & Observability

Health Checks

# Simple health check
curl https://your-server:3000/status
 
# Prometheus metrics (future)
curl https://your-server:3000/metrics

Logging

# View server logs
agentful serve --log-level=debug
 
# Structured logging
{
  "timestamp": "2025-01-22T10:30:00Z",
  "level": "info",
  "agent": "orchestrator",
  "task": "build_auth_system",
  "duration_ms": 45000,
  "llm_provider": "glm-4.7",
  "cost": "$0.23"
}

Metrics

Track important metrics:

  • Request latency
  • Agent success rate
  • LLM provider costs
  • Error rates
  • Resource usage

Full Monitoring Guide →

Scaling

Horizontal Scaling

# Kubernetes HPA
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: agentful-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: agentful-server
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

Load Balancing

# nginx load balancer
upstream agentful_servers {
  server agentful-1:3000;
  server agentful-2:3000;
  server agentful-3:3000;
}
 
server {
  listen 80;
  location / {
    proxy_pass http://agentful_servers;
  }
}

Full Scaling Guide →

Use Cases

Autonomous App Builder (Future Vision)

Mobile App (Voice Interface)
         ↓
    "Build me a todo app"
         ↓
    agentful Server
         ↓
┌─────────────────────────┐
│ 1. Architect: Design    │
│ 2. Backend: API         │
│ 3. Frontend: UI         │
│ 4. Tester: Tests        │
│ 5. Deploy: Production   │
└─────────────────────────┘
         ↓
    Working App Deployed

CI/CD Agent Execution

Git Push → GitHub Actions → agentful Server → Agents Execute → Tests Pass → Deploy

Remote Development Server

Developer → Web IDE → agentful API → Agents Code → Return Results

Multi-Tenant Agent Platform

Customer A → API Key → agentful → Isolated Environment
Customer B → API Key → agentful → Isolated Environment

Security Best Practices

Network Security

# 1. Use Tailscale (recommended)
agentful serve --auth=tailscale
 
# 2. Or firewall + HMAC
sudo ufw allow from 10.0.0.0/8 to any port 3000
agentful serve --auth=hmac
 
# 3. Never expose with --auth=none publicly
# BAD: agentful serve --auth=none --host=0.0.0.0
# GOOD: agentful serve --auth=tailscale

Secrets Management

# Use environment variables
export ANTHROPIC_API_KEY=$(cat /secrets/claude-key)
export AGENTFUL_SECRET=$(cat /secrets/hmac-secret)
 
# Or secret managers
# AWS Secrets Manager
# HashiCorp Vault
# Kubernetes Secrets

Rate Limiting

# Future feature: built-in rate limiting
agentful serve --rate-limit=100/minute --rate-limit-per-ip=10/minute

Full Security Guide →

Cost Analysis

Oracle Cloud Free Tier

Infrastructure: $0/month
LLM API (GLM-4.7): ~$60/month (100M tokens)
Total: $60/month
 
vs
 
Replit Agents: $100/month (hosted)
GitHub Copilot Enterprise: $390/month (10 users)
 
Savings: $330/month (85%)

Scaling Economics

10 users × 50M tokens/month = 500M tokens
 
Self-hosted (GLM-4.7):
Infrastructure: $0 (Oracle free tier)
LLM: 500M × $0.60/M = $300/month
Total: $300/month ($30/user)
 
Managed Service:
10 users × $40/user = $400/month
 
Break-even: ~8 users

Full Cost Analysis →

Next Steps