Run Autohand Code on AWS EC2

Provider docs used

This tutorial follows the shape of the AWS EC2 getting started guide: launch an instance, choose an image and instance type, attach a key pair, control inbound traffic with a security group, and connect with SSH. Keep the AWS guide open for current console labels and region-specific defaults: Get started with Amazon EC2.

Architecture

The EC2 instance is the Autohand Code runner. It holds a working copy of your repository, an Autohand Code config, provider credentials, and optional cron or systemd timers. Humans connect over SSH or AWS Systems Manager Session Manager; automation can call a local webhook endpoint through a private load balancer, API Gateway, or Cloudflare Tunnel.

Step 1: Launch the EC2 instance

1. Open the EC2 console and choose Launch instance.
2. Name the instance autohand-runner.
3. Select an Ubuntu LTS or Amazon Linux image.
4. Select an instance type that is large enough for your repository tests.
5. Create or select a key pair. Do not proceed without a key pair if you plan to use SSH.
6. In network settings, create a security group that allows SSH only from your trusted IP address or VPN CIDR.
7. Launch the instance and wait until instance status checks pass.

Step 2: Connect and create a runner user

Use the SSH command from the EC2 console's Connect tab. The user depends on your AMI, such as ubuntu for Ubuntu or ec2-user for Amazon Linux.

chmod 400 ~/.ssh/autohand-runner.pem
ssh -i ~/.ssh/autohand-runner.pem [email protected]

sudo adduser --disabled-password --gecos "" autohand
sudo usermod -aG sudo autohand
sudo su - autohand

Step 3: Install Node.js, Git, and Autohand Code

sudo apt-get update
sudo apt-get install -y ca-certificates curl git build-essential

# Install Node.js from your approved source, then verify:
node --version
npm --version

npm install -g autohand-cli
autohand --version

Pin the Autohand Code CLI version for production runners if your organization requires repeatable deployments.

Step 4: Configure credentials

Store model provider credentials in a file owned by the runner user, or inject them from AWS Secrets Manager into the shell environment before starting a job.

mkdir -p ~/.autohand
chmod 700 ~/.autohand

cat > ~/.autohand/env <<'EOF'
export OPENROUTER_API_KEY="sk-or-v1-..."
export AUTOHAND_MODEL="anthropic/claude-sonnet-4"
export AUTOHAND_OUTPUT_FORMAT="stream-json"
EOF
chmod 600 ~/.autohand/env
source ~/.autohand/env

Step 5: Clone and prepare the repository

mkdir -p ~/work ~/logs
cd ~/work
git clone [email protected]:your-org/your-repo.git
cd your-repo

autohand -p "Inspect this repository and update AGENTS.md with build, test, and style instructions for future headless jobs" --restricted

Step 6: Run the first EC2 job

Start with restricted mode so you can confirm access, model credentials, and logging before allowing changes.

source ~/.autohand/env
cd ~/work/your-repo

git pull --ff-only
autohand -p "Review the latest repository state and summarize the highest-priority issues" \
  --restricted \
  --output-format stream-json | tee -a ~/logs/review.jsonl

Step 7: Schedule or trigger jobs

Use cron for simple scheduled work. Use EventBridge, Systems Manager Run Command, GitHub Actions over SSH, or a small webhook process for triggered work.

crontab -e

# Weekday review at 08:00 UTC
0 8 * * 1-5 . $HOME/.autohand/env && cd $HOME/work/your-repo && git pull --ff-only && autohand -p "Review changes from the last 24 hours and list action items" --restricted --output-format json >> $HOME/logs/daily-review.jsonl 2>&1

Operations checklist

• Enable CloudWatch or your normal log shipper for ~/logs if jobs need central visibility.
• Use EBS snapshots before changing runner images or allowing write jobs.
• Rotate SSH keys, Git deploy keys, and model provider keys separately.
• Prefer --restricted for review jobs and explicit --yes only for narrow trusted write jobs.
• Terminate unused instances so idle runners do not continue accruing cost.