Configuration¶

This page covers where OpenHands Core keeps its settings, how to change your model, how to work on your own projects, and how to set up the optional Telegram bridge.

Where configuration lives¶

Host path	Inside the container	Contents
`/var/lib/sushi-openhands/state`	`/home/openhands/.openhands`	Settings, agent profiles, conversations, and the instance's session and encryption keys
`/var/lib/sushi-openhands/projects`	`/projects`	Project files the agent works on
`/etc/sushi/openhands-telegram.local.json`	not mounted	Telegram bridge configuration, if you create it

Both state folders are mode 0700 and owned by UID/GID 10001:10001, the user the container runs as.

The container is managed by the sushi-openhands systemd service. It runs with a 2 CPU and 3 GiB memory limit, publishes only 127.0.0.1:8000, and has no access to the host Docker socket or home folders.

Models¶

Configure providers, models and keys in Agent Canvas settings, not on the command line. To rotate a provider key, update it in the same settings.

Do not replace or regenerate the encryption key in /var/lib/sushi-openhands/state. Canvas uses it to decrypt your saved model settings.

Projects¶

The agent works in /projects inside the container. To give it your own code, copy it into a folder under the host projects path and give it to the container user:

sudo cp -r ~/<project> /var/lib/sushi-openhands/projects/<project>
sudo chown -R 10001:10001 /var/lib/sushi-openhands/projects/<project>

Then select /projects/<project> for the conversation in Agent Canvas.

Telegram bridge¶

The bridge lets you send tasks to OpenHands from one private Telegram chat. It is optional, installed but off, and has no bot or credentials until you add them. Finish the test task in the UI before you turn it on.

1. Prepare a dedicated bot¶

Create a new bot with BotFather in your own Telegram account. Use a bot that nothing else polls.
Note the bot token, the bot's numeric ID (the digits before : in the token), your private chat ID and your Telegram user ID.
In Agent Canvas, note the UUID of the agent profile the bridge should use. This is the profile's ID, not your provider key.

Treat the bot token as a secret. Keep it out of shell commands, URLs and logs.

2. Create the configuration file¶

Create the folder, then open the file in an editor as root:

sudo install -d -m 0755 /etc/sushi
sudoedit /etc/sushi/openhands-telegram.local.json

Paste this template and fill in your values:

{
  "bot_token": "",
  "expected_bot_id": 0,
  "chat_id": 0,
  "authorized_user_ids": [],
  "agent_profile_id": "00000000-0000-0000-0000-000000000000",
  "canvas_url": "http://127.0.0.1:8000",
  "max_iterations": 8,
  "task_timeout": 180
}

Field	Value
`bot_token`	Your bot token
`expected_bot_id`	The bot's numeric ID. Must match the token.
`chat_id`	Your private chat ID, a positive number
`authorized_user_ids`	Telegram user IDs allowed to send tasks. At least one.
`agent_profile_id`	The agent profile UUID from Agent Canvas
`canvas_url`	Leave as `http://127.0.0.1:8000`
`max_iterations`	Agent steps per task, 1 to 20. Default 8.
`task_timeout`	Seconds per task, 1 to 600. Default 180.

Empty tokens and zero IDs fail validation on purpose. Make the file root-only:

sudo chown root:root /etc/sushi/openhands-telegram.local.json
sudo chmod 0600 /etc/sushi/openhands-telegram.local.json

3. Check and start¶

Validate the file. This makes no network calls:

sudo python3 /opt/sushi/bin/openhands-telegram.py \
  --config /etc/sushi/openhands-telegram.local.json --check-config

Then turn on the bridge. It also starts on every boot:

sudo systemctl enable --now sushi-openhands-telegram.service

4. Send a task¶

In your private chat with the bot, start each task with /task, for example:

/task Run ID: <your-run-id> ...

The bridge only accepts /task messages from the allowed users in the allowed private chat, and ignores groups. It replies with the agent's final answer.

Change or remove the bot¶

To replace the token, stop the bridge first, edit the file, check it again, then start the bridge:

sudo systemctl stop sushi-openhands-telegram.service
sudo python3 /opt/sushi/bin/openhands-telegram.py \
  --config /etc/sushi/openhands-telegram.local.json --check-config
sudo systemctl start sushi-openhands-telegram.service

To turn the bridge off:

sudo systemctl disable --now sushi-openhands-telegram.service