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.
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
- The terminal displays a 6-digit pairing code and ASCII QR code.
- Open 01OS App on Mac or Android, navigate to the Agents tab, and enter the code or scan the QR code.
- Once confirmed, credentials are saved to
~/.hermes/oneos/{agent_id}.jsonwith restricted0600permissions.
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
- 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: ======================================================== - Open 01OS App on Mac or Android, go to the Agents section, and confirm the connection.
- 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
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.
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.
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.