Skip to content

Getting started

This page takes you from subscription to a first verified agent task. You launch the instance, sign in to the web UI 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 16 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 sushi-nanobot.service

The second command prints active.

On first boot, sushi-nanobot-firstboot.service creates the private configuration at /var/lib/nanobot/.nanobot/config.json, with a unique web UI password for this instance.

3. Get the web UI password

The web UI password is the channels.websocket.tokenIssueSecret value in the private configuration. Read it over a private SSH connection and save it to a file only you can read. From your workstation:

(umask 077; ssh -i <your-key.pem> ubuntu@<public-ip> \
  "sudo python3 -c 'import json; print(json.load(open(\"/var/lib/nanobot/.nanobot/config.json\"))[\"channels\"][\"websocket\"][\"tokenIssueSecret\"])'" \
  > nanobot-password.txt)

Keep the password private

Do not read it through Run Command, and keep it out of screenshots, logs and support messages. Anyone with the password and access to the tunnel can use the agent.

4. Open the UI through a tunnel

The web UI listens only on 127.0.0.1:8765 on the instance. Forward it to your workstation.

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

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

Leave the tunnel running, open http://127.0.0.1:8765 in your browser and sign in with the password.

5. Connect your model

In the web UI, open Settings → Models. Choose your provider and model, and enter your API key. The key is stored in the instance's private configuration.

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

6. Run a test task

A running service or a saved key does not prove that the agent works. 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/nanobot/.nanobot/workspace -name result.json

Next steps