Install Cachee Agent

How Agent-Based Monitoring Works

1

You install the Cachee agent on your EC2 instance (same VPC as ElastiCache)

2

Agent connects to your ElastiCache using the instance's own IAM role — no extra credentials needed

3

Agent reports metrics outbound via HTTPS to app.cachee.ai/api/metrics every 60 seconds

4

Your Cachee dashboard shows real-time hit rates, latency, and AI optimization recommendations

No inbound access from Cachee. The agent only makes outbound HTTPS calls. Your security group rules don't need to allow any traffic from Cachee's infrastructure.

Curl

Docker

Manual

SSH into your EC2 and run this single command. It installs Node.js (if needed), PM2, and the Cachee agent. ~90 seconds.

# Replace YOUR_KEY and YOUR_ENDPOINT curl -sSL https://app.cachee.ai/install.sh | bash -s -- \ --api-key YOUR_CACHEE_API_KEY \ --redis-url YOUR_ELASTICACHE_ENDPOINT:6379 \ --port 3000

After install, the agent starts automatically and survives reboots via PM2 + systemd.

What the script does:

1

Detects your OS (Amazon Linux, Ubuntu, RHEL) and architecture (x86_64, arm64/Graviton)

2

Installs Node.js 20 LTS and PM2 process manager (if not present)

3

Creates config at /etc/cachee/agent.yaml

4

Starts agent with PM2 and configures systemd startup

5

Runs health check and prints your agent URL

Run the Cachee agent as a Docker container. Ideal for ECS, EKS, or any Docker host.

docker run -d \ --name cachee-agent \ --restart unless-stopped \ -e CACHEE_API_KEY=YOUR_CACHEE_API_KEY \ -e REDIS_URL=YOUR_ELASTICACHE_ENDPOINT:6379 \ -e REPORT_URL=https://app.cachee.ai/api/metrics \ -p 3000:3000 \ cachee/agent:latest

Docker Compose

# docker-compose.yml version: '3.8' services: cachee-agent: image: cachee/agent:latest restart: unless-stopped ports: - "3000:3000" environment: CACHEE_API_KEY: YOUR_CACHEE_API_KEY REDIS_URL: YOUR_ELASTICACHE_ENDPOINT:6379 REPORT_URL: https://app.cachee.ai/api/metrics

ECS Task Definition

For Amazon ECS, add the Cachee agent as a sidecar container in your task definition. See ECS deployment guide.

Download the agent binary and configure it manually. Full control over every setting.

1. Download the Agent

# For x86_64 (Intel/AMD): curl -sSL https://cachee-public.s3.amazonaws.com/agent/cachee-agent-linux-amd64.tar.gz | sudo tar xz -C /opt/cachee/ # For aarch64 (Graviton/ARM): curl -sSL https://cachee-public.s3.amazonaws.com/agent/cachee-agent-linux-arm64.tar.gz | sudo tar xz -C /opt/cachee/

2. Create Configuration

# /etc/cachee/agent.yaml api_key: "ck_live_YOUR_API_KEY" redis_url: "your-cluster.abc123.use1.cache.amazonaws.com:6379" port: 3000 report_url: "https://app.cachee.ai/api/metrics" region: "us-east-1" metrics_interval: 60 optimization: predictive_prefetch: true compression: true deduplication: true log_level: info log_file: /var/log/cachee/agent.log

3. Create Systemd Service

# /etc/systemd/system/cachee-agent.service [Unit] Description=Cachee Cache Acceleration Agent After=network.target [Service] Type=simple User=root ExecStart=/usr/bin/node /opt/cachee/agent.js Restart=always RestartSec=5 Environment=NODE_ENV=production [Install] WantedBy=multi-user.target

4. Enable & Start

sudo systemctl daemon-reload sudo systemctl enable cachee-agent sudo systemctl start cachee-agent # Verify: curl http://localhost:3000/health

Security Group Requirements

Your EC2 security group must allow:

1

Inbound TCP port 3000 (or your configured port) from your application servers — so they can route cache requests through Cachee

2

Outbound HTTPS (443) to app.cachee.ai — for metrics reporting (usually already allowed by default SG rules)

3

Outbound TCP 6379 to your ElastiCache security group — for cache operations

EC2 and ElastiCache must be in the same VPC and region. Cross-VPC or cross-region adds 50-200ms latency and defeats the purpose of caching.

Troubleshooting

Agent won't start

Check logs: pm2 logs cachee-agent or journalctl -u cachee-agent -f

Can't connect to ElastiCache

Ensure the ElastiCache security group allows inbound TCP 6379 from your EC2's security group. Both must be in the same VPC.

Metrics not showing in dashboard

Verify outbound HTTPS is allowed: curl -v https://app.cachee.ai/api/health-check. Check that your API key is correct in /etc/cachee/agent.yaml.

Health check fails in wizard

The wizard probes http://YOUR_IP:3000/api/v1/health. Ensure your EC2 security group allows inbound TCP 3000 from 0.0.0.0/0 (or at minimum from Cachee's verification IPs).