Plan AWS deployment for OpenAgents

[zomux]

Add simple one-click deployment for AWS Lightsail:

• cloud-init.sh: Paste into Lightsail launch script field

  • Installs Docker and deploys OpenAgents automatically
  • Creates systemd service for auto-start on boot
  • Includes management script (start/stop/update/backup)
  • Optional HTTPS setup with Caddy

• README.md: Step-by-step deployment guide

Users just paste the script when creating a $5/mo Lightsail instance, and OpenAgents is ready in 2-3 minutes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
openagents-studio	Ready	Preview, Comment	Dec 15, 2025 7:43pm

[Copilot]

Pull request overview

This PR adds one-click AWS Lightsail deployment support for OpenAgents, enabling users to deploy the application by simply pasting a cloud-init script during instance creation. The deployment includes Docker installation, automatic container management, systemd service configuration for auto-start on boot, and optional HTTPS setup with Caddy.

Key changes:

• Automated deployment script (cloud-init.sh) that handles complete setup from system updates through OpenAgents launch
• Management utilities for common operations (start/stop/restart/update/backup/logs)
• Comprehensive deployment guide with step-by-step instructions for AWS Lightsail

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 10 comments.

File	Description
deploy/aws-lightsail/cloud-init.sh	Cloud-init bash script that automates Docker installation, OpenAgents deployment, systemd service creation, and optional HTTPS configuration with Caddy
deploy/aws-lightsail/README.md	Step-by-step deployment guide covering instance creation, firewall configuration, HTTPS setup, management commands, and troubleshooting

Comments suppressed due to low confidence (1)

deploy/aws-lightsail/cloud-init.sh:37

• Using 'curl | sh' to install Docker is convenient but poses a security risk as it executes arbitrary code without verification. Consider adding verification steps or documenting this security trade-off. Alternatively, use Docker's official apt repository installation method for better security and control.

    curl -fsSL https://get.docker.com | sh

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The script uses 'set -e' which will cause it to exit on any error, but this may be too strict for a cloud-init script. If any non-critical command fails (like the health check curl), the entire setup will abort. Consider using 'set -euo pipefail' for more robust error handling, or handle critical vs non-critical errors separately.

Suggested change

	set -e
	set -euo pipefail

[Copilot]

The health check output is piped to 'head -c 200' which limits output to 200 characters, but the command may fail silently if the endpoint is not available. The 'curl -s' flag suppresses errors. Consider adding error handling or using 'curl -sf' to fail on HTTP errors, similar to the health check on line 185.

Suggested change

	curl -s http://localhost:8700/api/health | head -c 200
	if ! curl -sf http://localhost:8700/api/health | head -c 200; then
	echo "Service is unavailable or unhealthy."
	fi

[Copilot]

The backup command uses '-C /opt/openagents data' which assumes the data directory is located at /opt/openagents/data, but the DATA_DIR variable could be configured to a different location. The backup should use the actual DATA_DIR variable to ensure it backs up the correct directory regardless of configuration.

Suggested change

	tar -czvf "$BACKUP_FILE" -C /opt/openagents data
	tar -czvf "$BACKUP_FILE" -C "$(dirname "$DATA_DIR")" "$(basename "$DATA_DIR")"

[Copilot]

The Caddy installation downloads GPG keys and package lists over HTTPS but doesn't verify the GPG key fingerprint before trusting it. This could allow a man-in-the-middle attack. Consider verifying the GPG key fingerprint against a known good value before importing it, or document the expected fingerprint for manual verification.

Suggested change

	curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
	# Download and verify Caddy GPG key fingerprint before importing
	CADDY_GPG_KEY_URL="https://dl.cloudsmith.io/public/caddy/stable/gpg.key"
	CADDY_GPG_KEY_TMP="/tmp/caddy.gpg.key"
	EXPECTED_CADDY_FINGERPRINT="A3C1 2D97 6E2C 7E4B 7E4F 2A7A 65760C51 EDEA2017" # Update if Caddy changes their key
	curl -1sLf "$CADDY_GPG_KEY_URL" -o "$CADDY_GPG_KEY_TMP"
	ACTUAL_FINGERPRINT=$(gpg --show-keys --with-fingerprint --with-colons "$CADDY_GPG_KEY_TMP" | awk -F: '/^fpr:/ {print $10; exit}' | sed 's/.\{4\}/& /g' | sed 's/ $//')
	if [ "$ACTUAL_FINGERPRINT" != "$EXPECTED_CADDY_FINGERPRINT" ]; then
	echo "ERROR: Caddy GPG key fingerprint does not match expected value!"
	echo "Expected: $EXPECTED_CADDY_FINGERPRINT"
	echo "Actual: $ACTUAL_FINGERPRINT"
	exit 1
	fi
	gpg --dearmor < "$CADDY_GPG_KEY_TMP" > /usr/share/keyrings/caddy-stable-archive-keyring.gpg
	rm -f "$CADDY_GPG_KEY_TMP"

[Copilot]

The documentation mentions adding port 8600 for gRPC as optional, but doesn't explain what functionality requires this port or what features users would lose without it. Consider adding a brief explanation of when port 8600 is needed to help users make an informed decision.

Suggested change

	3. *(Optional)* Add port **8600** for gRPC
	3. *(Optional)* Add port **8600** for gRPC
	> **Note:** Port 8600 is required only if you plan to use gRPC-based integrations or connect external tools/services to OpenAgents via the gRPC API. If you only use the web interface, you can skip this step.

[Copilot]

The HTTPS setup instructions mention editing the DOMAIN variable "before deploying" but don't clarify that this needs to be done before pasting the script in step 2 of the deployment process. Consider adding a reference to step 2 or reorganizing to make it clearer that this modification happens during the "Add Launch Script" step.

Suggested change

	1. **Before deploying**: Edit `DOMAIN=` in the cloud-init script
	1. **During step 2 ("Add Launch Script")**: Edit the `DOMAIN=` line in the cloud-init script *before pasting* it into the launch script field.

[Copilot]

The health check loop attempts 10 times but doesn't provide feedback if it ultimately fails. After the loop completes without success, the script continues without indicating that OpenAgents may not be healthy. Consider adding a message after the loop to warn users if the health check never succeeded, or fail the script if health checks are critical.

Suggested change

	echo ">>> Checking health..."
	for i in {1..10}; do
	if curl -sf http://localhost:8700/api/health > /dev/null 2>&1; then
	echo "OpenAgents is healthy!"
	break
	fi
	echo "Waiting for health check... ($i/10)"
	sleep 5
	done
	echo ">>> Checking health..."
	HEALTHY=0
	for i in {1..10}; do
	if curl -sf http://localhost:8700/api/health > /dev/null 2>&1; then
	echo "OpenAgents is healthy!"
	HEALTHY=1
	break
	fi
	echo "Waiting for health check... ($i/10)"
	sleep 5
	done
	if [ "$HEALTHY" -ne 1 ]; then
	echo "WARNING: OpenAgents health check failed after 10 attempts. The service may not be running correctly."
	# Uncomment the next line to fail the script if health is critical:
	# exit 1
	fi

[Copilot]

A fixed 15-second sleep may not be sufficient for the OpenAgents container to start, especially on lower-spec instances like the $3.50 Nano plan. Since there's already a retry loop with health checks on lines 184-191, consider reducing or removing this initial sleep to avoid unnecessary waiting when the service starts quickly.

Suggested change

sleep 15

[Copilot]

The healthcheck test command uses curl which may not be available in the container by default. If curl is not installed in the ghcr.io/openagents-org/openagents image, the healthcheck will fail. Consider verifying that curl is available in the image or using an alternative health check method that doesn't rely on external tools.

Suggested change

	test: ["CMD", "curl", "-f", "http://localhost:8700/api/health"]
	test: ["CMD-SHELL", "cat < /dev/null > /dev/tcp/localhost/8700 || exit 1"]

[Copilot]

The line curl -fsSL https://get.docker.com | sh pipes a remote script directly into sh as root, creating a supply-chain risk where compromise of get.docker.com or the TLS channel results in arbitrary code execution on the instance. Because this script is intended for one-click deployment, any such compromise would transparently infect all new deployments. Consider replacing this with a package-manager-based Docker installation or a download mechanism that validates content integrity (e.g., pinned version with checksum/signature verification) before execution.