Developer & Agent Documentation

Public Agent Connection Guide

Connect your agent to 01OS: outbound HTTPS long-polling over standard Bot API channels with unified Mac, Android, and 01 Watch interaction.

Protocol: 2.0 · Updated: November 2, 2026 · Supported Agents: Hermes, Muse, and custom Bot API clients
💡 Suitable for Direct Agent Reading

You can provide this document URL (https://01os.ai/en/connect/) directly to your AI agent. It can read instructions, extract installation commands, setup hooks, and perform pairing autonomously.

1. Core Architecture & Boundary Model

01OS is a third-party AI agent cockpit. Users interact with their own agents on Mac and Android, switch agents on 01 Watch, talk via push-to-talk, and approve decisions with a glance and nod.

Layer Ownership Boundary & Responsibility
Agent Models & Tools Third-party Environment All LLM keys, local tool executions, system prompts, and memory stay in the agent's host environment. 01OS never takes over or hosts upstream credentials.
Bot API Channel 01OS Gateway (HTTPS) Agent initiates outbound HTTPS long-polling (getUpdates) to fetch messages and replies via sendMessage. No public IP or inbound firewall opening is required.
Approval & Nodding User & Agent Direct Contract Nodding approval on 01 Watch or App constitutes direct user authorization to the agent. 01OS never approves actions on behalf of users.
Voice & Audio 01 Watch + Cloud ASR Voice is transcribed to text on the gateway and delivered to the agent as standard text. 01OS V1 does not perform TTS (text-to-speech).

2. Hermes Agent Integration

If your agent runs on Hermes, use the official hermes-oneos platform channel plugin.

2.1 Prerequisites

  • Hermes Agent >= 0.22.0
  • Python >= 3.10
  • Dependency: aiohttp

2.2 Installation

Install the plugin directly inside your Hermes environment:

hermes plugins install https://github.com/Ericwong5021/01-home-os.git#plugins/hermes-oneos

2.3 Pairing & Setup

Launch the gateway setup wizard and choose 01OS:

hermes gateway setup
  1. The terminal displays a 6-digit pairing code and ASCII QR code.
  2. Open 01OS App on Mac or Android, navigate to the Agents tab, and enter the code or scan the QR code.
  3. Once confirmed, credentials are saved to ~/.hermes/oneos/{agent_id}.json with restricted 0600 permissions.

2.4 Run Service

hermes gateway run

The plugin continuously polls 01OS for user prompts and streams back replies. The persistent instance_id ensures conversation threads and watch configurations are preserved across re-connections.

3. Muse VM Service Integration

For Muse agents operating in a Linux VM, 01OS provides the dedicated 01os-muse IO service client, managing outbound message polling, official Hook invocation, and atomic state handling.

3.1 One-Line Installer

Run the following command inside your Muse VM (Ubuntu / Debian):

curl -fsSL https://01os.ai/connect/install-muse.sh | bash

The script auto-detects architecture (x86_64 or aarch64), downloads the release package from GitHub Releases, verifies SHA-256 checksums, and configures permissions in ~/01os-muse.

3.2 Manual Download & Checksums (GitHub Releases)

Direct download links for official release binaries:

Architecture Direct Download (01OS Official Mirror) GitHub Release Mirror Type
Linux x86_64 (amd64) 01os-muse-v0.2.0-linux-amd64.tar.gz Release v0.2.0 Static 64-bit ELF Binary
Linux aarch64 (arm64) 01os-muse-v0.2.0-linux-arm64.tar.gz Release v0.2.0 Static 64-bit ELF Binary
Universal Python Bundle 01os-muse-v0.2.0-universal.tar.gz Release v0.2.0 Cross-platform script package
Checksums SHA256SUMS.txt SHA256SUMS.txt SHA-256 Fingerprints

3.3 Initial Startup & Pairing

Start the client to initiate pairing with 01OS:

cd ~/01os-muse
./01os-muse client --base-url https://app.01os.ai
  1. The terminal outputs a 6-character uppercase pairing code and QR code:
    ========================================================
      01OS Pairing Code: 4K8M2P
      Enter this code in 01OS App (Mac or Android) to connect,
      or scan the QR code below:
    ========================================================
  2. Open 01OS App on Mac or Android, go to the Agents section, and confirm the connection.
  3. Credentials are written securely to ~/01os-muse/account.json (0600 mode).

3.4 Muse Official Hook Integration

Create the hook wrapper script ~/01os-muse/run_hook.sh:

#!/usr/bin/env bash
set -euo pipefail
ROOT="$HOME/01os-muse"
CLAIMS="$ROOT/hook.claims"
OUTPUT=$("$ROOT/01os-muse" hook-check --root "$ROOT" --claims "$CLAIMS")
if [ "$OUTPUT" != "null" ] && [ -n "$OUTPUT" ]; then
  echo "wake: $OUTPUT"
else
  echo "silent"
fi

Make it executable and configure the periodic hook runner (recommended every 5s):

chmod 0700 ~/01os-muse/run_hook.sh

When awakened, Hook Workers process tasks guided by hook-worker.md and emit replies via emit-reply:

~/01os-muse/01os-muse emit-reply \
  --root ~/01os-muse \
  --request-id <REQUEST_UUID> \
  --connection-id <CONNECTION_UUID> \
  --final \
  --text 'Here is the response from Muse'

3.5 Systemd Daemon Setup

Create ~/.config/systemd/user/01os-muse.service:

[Unit]
Description=01OS Muse IO Client
After=network.target

[Service]
Type=simple
WorkingDirectory=%h/01os-muse
ExecStart=%h/01os-muse/01os-muse client --base-url https://app.01os.ai --state-dir %h/01os-muse
Restart=always
RestartSec=5
RestartPreventExitStatus=2
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

Reload and start the service:

systemctl --user daemon-reload
systemctl --user enable --now 01os-muse

3.6 Status & Updates

Inspect service state, lock ownership, and queue metrics:

~/01os-muse/01os-muse status

Update to the latest release in-place:

~/01os-muse/01os-muse update
systemctl --user restart 01os-muse

4. FAQ & Troubleshooting

Q: Will rebooting the VM or re-pairing lose conversation history?

No. The client creates a persistent instance_id upon first initialization. As long as this file is kept, re-pairing automatically binds to your existing agent ID and preserves watch slots and history.

Q: What are the attachment limitations?

Up to 20 MiB per file and a maximum of 10 attachments per message. Supported types include PNG, JPEG, WebP images, and WAV, MP3, OGG audio.

Q: Why are approval cards and task boards displayed as text?

Approval cards and Kanban board endpoints are in early preview (gateway returns 501). The client gracefully falls back to text prompts so no user action is missed.