Skip to content

Getting started

This page takes you from subscription to a first verified agent task. You launch the instance, open Agent Zero through a private tunnel, connect your model provider and check that the agent really runs tools.

Before you start

  • A model provider account, an API key and enough quota. Provider charges are separate from AWS.
  • On your workstation: an SSH client, or the AWS CLI with the Session Manager plugin.

1. Subscribe and launch

  1. Open the listing and subscribe.
  2. Launch the AMI on t3.medium or larger (x86_64), with IMDSv2 and a gp3 root volume of at least 40 GiB. Turn on EBS encryption if your policies require it.
  3. Allow outbound HTTPS to your model provider, and to Telegram if you plan to use it.
  4. Choose how you will connect:
    • SSH: select your EC2 key pair, and set the TCP 22 rule to your administrator CIDR. The listing's default security group allows 22 only from 127.0.0.1/32, which blocks SSH until you change it.
    • Session Manager: attach an instance profile that allows AWS Systems Manager. The application itself needs no AWS credentials.

2. Wait for automatic startup

First startup can take several minutes. Connect to the instance as ubuntu, then wait for cloud-init and check the service:

sudo cloud-init status --wait
sudo systemctl is-active agent-zero-core.service

The second command prints active. To confirm the UI answers on the instance:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5080/

3. Open the UI through a tunnel

Agent Zero listens only on 127.0.0.1:5080 on the instance. Forward it to your workstation.

ssh -i <your-key.pem> -L 5080:127.0.0.1:5080 ubuntu@<public-ip>

aws ssm start-session \
  --region <region> \
  --target <instance-id> \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["5080"],"localPortNumber":["5080"]}'

Leave the tunnel running and open http://127.0.0.1:5080 in your browser.

4. Connect your model

Agent Zero starts a setup wizard on your first message:

  1. Choose Cloud provider, then your provider.
  2. Choose the Main Model.
  3. Choose the utility model.
  4. Choose Finish setup.

Enter your provider API key when the wizard asks for it.

"Ready" in the wizard means your settings were saved. It does not prove the model works. The next step does.

Keep keys out of shell commands, user data, logs and screenshots.

5. Run a test task

Send this task with your own run ID:

Run ID: <your-run-id>
In your allowed workspace, create e2e_<your-run-id>/input.csv with exactly:
value
5
17
20
Use native file/terminal tools to read the CSV and assert values [5,17,20],
sum 42 and row count 3. Write result.json containing run_id, sum=42,
row_count=3 and passed=true. Read result.json back with a separate tool call.
Reply in English with the run ID and verified result. Stop after this task.

Expect the agent to run tools, reply with a total of 42 and three rows, and leave a matching result.json on disk. Check the files yourself on the instance:

sudo find /var/lib/agent-zero-core/usr -name result.json

Next steps