Skip to content

Getting started

This page takes you from subscription to a first verified agent task. You launch the instance, open Agent Canvas 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 32 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 the bridge.
  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.

Keep port 8000 closed in the security group.

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 sushi-openhands.service

The second command prints active. To confirm the server is ready to serve requests:

curl -s http://127.0.0.1:8000/ready

The response contains "status": "ready".

On first start, the service creates the instance's own session and encryption keys. Nothing is shared with other instances.

3. Open the UI through a tunnel

Agent Canvas listens only on 127.0.0.1:8000 on the instance. Forward it to your workstation.

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

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

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

Keep the UI inside the tunnel

The page includes the instance's session key. Do not expose port 8000, and do not share screenshots of the page source or settings.

4. Connect your model

In Agent Canvas, open the settings and create an agent profile backed by your cloud model provider. Choose the provider and model, and enter your API key there. Keys are stored in the instance's private state, encrypted with the instance's own key.

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

Small Claude test tasks

For a short, bounded test with an Anthropic Claude model, set the profile's reasoning effort to none and its extended thinking budget to 0. Without that, a low output-token limit can produce a provider configuration error.

5. Run a test task

A running service or a saved key does not prove that the agent works. Send this task in a new conversation, 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/sushi-openhands/projects -name result.json

Next steps