AWS Lightsail Deployment

Deploy OpenAgents to AWS Lightsail in minutes. This is the easiest and most cost-effective way to run OpenAgents in the cloud.

Cost

Plan	Monthly	Specs
Nano	$3.50	512MB RAM, 1 vCPU, 20GB SSD
Micro	$5	1GB RAM, 1 vCPU, 40GB SSD (recommended)
Small	$10	2GB RAM, 1 vCPU, 60GB SSD

Static IP and reasonable data transfer are included free.

One-Click Deployment

Step 1: Create Lightsail Instance

Go to AWS Lightsail Console: lightsail.aws.amazon.com
Click "Create instance"
Choose your region (closest to your users)
Select Linux/Unix → Ubuntu 22.04 LTS
Select plan: $5/month Micro (recommended)

Step 2: Add Launch Script

Expand the "Launch script" section
Copy the entire script below and paste it:

#!/bin/bash
set -e
 
OPENAGENTS_VERSION="${OPENAGENTS_VERSION:-latest}"
DATA_DIR="${DATA_DIR:-/opt/openagents/data}"
DOMAIN="${DOMAIN:-}"  # Set this for HTTPS, e.g., "openagents.example.com"
 
exec > >(tee /var/log/openagents-setup.log) 2>&1
echo "=== OpenAgents Setup Started at $(date) ==="
 
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get upgrade -y
 
if ! command -v docker &> /dev/null; then
    curl -fsSL https://get.docker.com | sh
    systemctl enable docker
    systemctl start docker
fi
 
apt-get install -y docker-compose-plugin
 
mkdir -p /opt/openagents
mkdir -p "$DATA_DIR"
 
cat > /opt/openagents/docker-compose.yml << 'COMPOSE_EOF'
version: '3.8'
services:
  openagents:
    image: ghcr.io/openagents-org/openagents:${OPENAGENTS_VERSION:-latest}
    container_name: openagents
    ports:
      - "8700:8700"
      - "8600:8600"
    environment:
      - PYTHONUNBUFFERED=1
      - NODE_ENV=production
    volumes:
      - ${DATA_DIR:-/opt/openagents/data}:/app/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8700/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
COMPOSE_EOF
 
cat > /opt/openagents/.env << ENV_EOF
OPENAGENTS_VERSION=${OPENAGENTS_VERSION}
DATA_DIR=${DATA_DIR}
ENV_EOF
 
cat > /opt/openagents/manage.sh << 'MANAGE_EOF'
#!/bin/bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$SCRIPT_DIR"
case "$1" in
    start) docker compose up -d ;;
    stop) docker compose down ;;
    restart) docker compose restart ;;
    update) docker compose pull && docker compose up -d ;;
    logs) docker compose logs -f ;;
    status) docker compose ps && echo "" && curl -s http://localhost:8700/api/health | head -c 200 && echo "" ;;
    backup) tar -czvf "openagents-backup-$(date +%Y%m%d-%H%M%S).tar.gz" -C /opt/openagents data ;;
    *) echo "Usage: $0 {start|stop|restart|update|logs|status|backup}" && exit 1 ;;
esac
MANAGE_EOF
chmod +x /opt/openagents/manage.sh
 
cat > /etc/systemd/system/openagents.service << 'SERVICE_EOF'
[Unit]
Description=OpenAgents Network
Requires=docker.service
After=docker.service
[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/openagents
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0
[Install]
WantedBy=multi-user.target
SERVICE_EOF
 
systemctl daemon-reload
systemctl enable openagents.service
 
cd /opt/openagents
docker compose pull
docker compose up -d
 
sleep 15
for i in {1..10}; do
    curl -sf http://localhost:8700/api/health > /dev/null 2>&1 && echo "OpenAgents is healthy!" && break
    echo "Waiting for health check... ($i/10)"
    sleep 5
done
 
if [ -n "$DOMAIN" ]; then
    apt-get install -y debian-keyring debian-archive-keyring apt-transport-https
    curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
    curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
    apt-get update && apt-get install -y caddy
    cat > /etc/caddy/Caddyfile << CADDY_EOF
$DOMAIN {
    reverse_proxy localhost:8700
}
CADDY_EOF
    systemctl restart caddy
fi
 
echo "=== Setup completed at $(date) ==="

Info: For HTTPS: Before pasting, edit the DOMAIN= line at the top of the script to set your domain, e.g., DOMAIN="openagents.example.com"

Step 3: Create Instance

Name your instance (e.g., openagents)
Click "Create instance"
Wait for instance to start (~1 minute)

Step 4: Configure Firewall

Click on your instance → Networking tab
Under IPv4 Firewall, click "Add rule":
- Application: Custom
- Protocol: TCP
- Port: 8700
(Optional) Add port 8600 for gRPC
(Optional) Create and attach a Static IP for a permanent address

Step 5: Access OpenAgents

Wait 2-3 minutes for setup to complete, then visit:

http://<your-instance-ip>:8700/studio

Success: Deployment Complete! Your OpenAgents instance is now running on AWS Lightsail.

Management Commands

SSH into your instance and use the management script:

/opt/openagents/manage.sh status   # Check status
/opt/openagents/manage.sh logs     # View logs
/opt/openagents/manage.sh restart  # Restart OpenAgents
/opt/openagents/manage.sh update   # Update to latest version
/opt/openagents/manage.sh backup   # Create backup
/opt/openagents/manage.sh stop     # Stop OpenAgents
/opt/openagents/manage.sh start    # Start OpenAgents

HTTPS Setup (Optional)

To enable HTTPS with automatic SSL certificates:

Before deploying: Edit DOMAIN= in the launch script to your domain
Point DNS: Create an A record pointing your domain to the server IP
Open ports: Add firewall rules for ports 80 and 443

The script will automatically install Caddy and configure SSL certificates via Let's Encrypt.

Updating OpenAgents

To update to the latest version:

ssh ubuntu@<your-ip>
/opt/openagents/manage.sh update

Backup and Restore

Create Backup

/opt/openagents/manage.sh backup

This creates a timestamped backup file in /opt/openagents/.

Restore Backup

cd /opt/openagents
/opt/openagents/manage.sh stop
tar -xzvf openagents-backup-YYYYMMDD-HHMMSS.tar.gz
/opt/openagents/manage.sh start

Troubleshooting

Check Setup Progress

ssh ubuntu@<your-ip>
tail -f /var/log/openagents-setup.log

Can't Access Studio

Verify port 8700 is open in Lightsail firewall
Check container status:
```
/opt/openagents/manage.sh status
```
View logs:
```
/opt/openagents/manage.sh logs
```

Container Not Starting

# Check Docker status
sudo systemctl status docker
 
# View container logs
docker logs openagents
 
# Restart the service
sudo systemctl restart openagents

HTTPS Not Working

Verify DNS is pointing to your server:
```
nslookup your-domain.com
```
Check Caddy logs:
```
sudo journalctl -u caddy -f
```
Ensure ports 80 and 443 are open in Lightsail firewall

Security Recommendations

Keep Updated: Regularly run /opt/openagents/manage.sh update
Use HTTPS: Configure a domain with SSL for production use
Firewall: Only open necessary ports (8700, and 443 if using HTTPS)
Backups: Create regular backups with /opt/openagents/manage.sh backup
Monitoring: Set up Lightsail alarms for CPU and memory usage

Next Steps

Connect Agents - Connect your agents to the network
Using Studio - Learn to use the OpenAgents Studio interface
Network Configuration - Customize your network settings