OpenOcto

https://github.com/xspadex/openocto
Admin
OpenOcto is an AI agent platform and relay system that enables users to remotely control and monitor...
Tokens:3,223
Snippets:45
Trust Score:5.1
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Installation and Configuration

Source: https://github.com/xspadex/openocto/blob/main/README.md

Commands to install the package and initiate the interactive setup process.

```bash
pip install openocto
octo setup             # AI-guided setup — walks you through everything interactively
```

--------------------------------

### octo setup

Source: https://github.com/xspadex/openocto/blob/main/README.md

Initiates the AI-guided setup wizard for configuring the OpenOcto environment.

```APIDOC
## octo setup

### Description
AI-guided setup wizard for initial configuration.

### Usage
`octo setup`
```

--------------------------------

### Octo-Agent Configuration Example

Source: https://github.com/xspadex/openocto/blob/main/android/octo-agent.example.md

Place this configuration file at /sdcard/.octo/octo-agent.md to define agent behavior and preferences.

```markdown
name: MyPhone
role: Personal phone assistant
owner: your-name

## Rules
- Always confirm before making calls or sending SMS
- Respond in Chinese by default
- Use TTS to announce important notifications

## Contacts
- Boss: 138xxxx1234
- Mom: 139xxxx5678

## Preferences
- Alarm sound: gentle
- Default SMS language: Chinese
- Wake me up at 7:00 on weekdays
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/xspadex/openocto/blob/main/CONTRIBUTING.md

Sets up a Python virtual environment and installs the package in editable mode with all development and feature-specific dependencies.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,qr,nearby,metrics]"
```

--------------------------------

### Install Core Dependencies

Source: https://github.com/xspadex/openocto/blob/main/CONTRIBUTING.md

Installs the package in editable mode with only the core development dependencies.

```bash
pip install -e ".[dev]"
```

--------------------------------

### octo join

Source: https://github.com/xspadex/openocto/blob/main/README.md

Starts the OpenOcto daemon to join a network.

```APIDOC
## octo join

### Description
Start the daemon to join a network.

### Parameters
- **--name** (string) - Required - Name of the node.
- **--tags** (string) - Optional - Comma-separated tags.
- **--ssh** (string) - Optional - Forward via SSH (user@host).
- **--daemon** (flag) - Optional - Run in background.
```

--------------------------------

### CLI Reference Commands

Source: https://github.com/xspadex/openocto/blob/main/README.md

Comprehensive list of available CLI commands for setup, remote operations, terminal management, network configuration, and agent integration.

```text
Setup:
  octo setup                             AI-guided setup wizard (recommended)
  octo init                              Manual relay configuration
  octo token [--qr]                      Generate join token
  octo join --name NAME [options]        Start daemon
       --tags T                          Comma-separated tags
       --ssh user@host                   Forward via SSH
       --daemon                          Run in background

Remote Operations:
  octo run TARGET "COMMAND"              Execute command
       --notify TERMINAL                 Notify when done
       --notify-message MSG              Custom notification message
  octo cat TARGET /path                  Read file
  octo edit TARGET /path --old X --new Y Edit file
  octo glob TARGET "**/*.py"             Search files by pattern
  octo grep TARGET "pattern"             Search file contents
  octo logs TARGET [-f] [--tail N]       View task output
  octo kill TARGET                       Kill running command
  octo send SOURCE TARGET FILE           Transfer file
  octo metrics TARGET                    GPU + training metrics
  octo metrics --dashboard               Open web dashboard

Terminal Management:
  octo ls                                List all terminals
  octo wake TARGET                       Fast polling
  octo cool TARGET                       Low-power polling

Network & Permissions:
  octo network create NAME [--public]    Create network
  octo register NAME                     Register device identity
  octo invite TARGET --role ROLE         Generate invite
  octo acl TARGET [--default R]          Manage access

Agent:
  octo agent-md                          Generate CLAUDE.md
  octo agent --backend claude            Start Claude Code with phone sync
  octo agent --backend codex             Start Codex with phone sync
  octo agent-serve --backend codex-cli   Start Codex agent daemon
  octo mcp-server                        Start MCP server
```

--------------------------------

### Optional Package Extras

Source: https://github.com/xspadex/openocto/blob/main/README.md

Additional installation options for specific features like QR codes, BLE transfer, and metrics parsing.

```bash
pip install "openocto[qr]"       # QR output for `octo token --qr`
pip install "openocto[nearby]"   # BLE + encrypted nearby transfer
pip install "openocto[metrics]"  # TensorBoard/tfevents parsing helpers
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/xspadex/openocto/blob/main/README.md

Common commands for managing remote terminals, running tasks, and file operations.

```bash
octo ls                              # See all terminals
octo run gpu "nvidia-smi"            # Run a command
octo run gpu "python train.py"       # Start training
octo run gpu "python train.py" --notify phone  # Notify phone when done
octo cat gpu /work/model.py          # Read a remote file
octo edit gpu /work/config.py --old "lr=0.001" --new "lr=0.0005"
octo kill gpu                        # Kill running command
```

--------------------------------

### Configure cloud storage

Source: https://github.com/xspadex/openocto/blob/main/README.md

Opens the configuration prompt for S3-compatible storage providers.

```bash
octo config --storage         # S3 endpoint, keys, bucket
```

--------------------------------

### Run Common Development Commands

Source: https://github.com/xspadex/openocto/blob/main/CONTRIBUTING.md

Executes standard project tasks including running tests, building the package, and verifying distribution files.

```bash
pytest -q
python -m build
python -m twine check dist/*
```

--------------------------------

### Project Directory Structure

Source: https://github.com/xspadex/openocto/blob/main/README.md

Overview of the core source files and their responsibilities within the OpenOcto project.

```text
src/openocto/
├── relay.py              Upstash Redis REST client (atomic Lua CAS)
├── daemon.py             Worker: poll, execute, stream results
├── cli.py                CLI (20+ subcommands)
├── mcp_server.py         MCP server (11 structured tools)
├── storage.py            S3-compatible file transfer (parallel multipart)
├── permissions.py        Role-based ACL engine
├── signing.py            Ed25519 task signing & verification
├── config.py             Config & join token encoding
├── metrics_dashboard.py  GPU metrics web dashboard
└── agent_md.py           CLAUDE.md generator
```

--------------------------------

### Manage public network access

Source: https://github.com/xspadex/openocto/blob/main/README.md

Sets up a public network, registers users with Ed25519 keys, and manages access permissions.

```bash
octo network create mylab --public
octo register alice                       # Generate Ed25519 keypair
octo invite gpu --role readwrite          # Share access
```

--------------------------------

### Monitor GPU Metrics

Source: https://github.com/xspadex/openocto/blob/main/README.md

Access GPU utilization and training metrics via the CLI or a web-based dashboard.

```bash
octo metrics gpu                    # One-shot: print GPU status + training metrics
octo metrics --dashboard            # Open web dashboard (all GPU servers)
```

--------------------------------

### Configure Training Notifications

Source: https://github.com/xspadex/openocto/blob/main/README.md

Use the --notify flag to receive alerts on your phone when a training job completes or fails.

```bash
octo run gpu "python train.py" --notify phone
octo run gpu "python train.py" --notify phone --notify-message "Experiment A done"
```

--------------------------------

### MCP Configuration

Source: https://github.com/xspadex/openocto/blob/main/README.md

Configuration snippet for integrating OpenOcto with MCP-compatible agents like Claude Code.

```json
{
  "mcpServers": {
    "openocto": {
      "command": "octo",
      "args": ["mcp-server"]
    }
  }
}
```

--------------------------------

### Generate join tokens

Source: https://github.com/xspadex/openocto/blob/main/README.md

Prints or displays a QR code for a join token to connect additional machines without re-initializing.

```bash
octo token                    # prints octo://eyJ...
octo token --qr               # or show QR code (for phone)
```

--------------------------------

### octo metrics

Source: https://github.com/xspadex/openocto/blob/main/README.md

Retrieves GPU and training metrics from a target or opens the web dashboard.

```APIDOC
## octo metrics

### Description
View GPU and training metrics.

### Parameters
- **TARGET** (string) - Optional - The target node to query.
- **--dashboard** (flag) - Optional - Open the web dashboard.
```

--------------------------------

### octo run

Source: https://github.com/xspadex/openocto/blob/main/README.md

Executes a command on a specified target node.

```APIDOC
## octo run

### Description
Execute a command on a target node.

### Parameters
- **TARGET** (string) - Required - The target node identifier.
- **COMMAND** (string) - Required - The command to execute.
- **--notify** (string) - Optional - Notify when done (e.g., TERMINAL).
- **--notify-message** (string) - Optional - Custom notification message.
```

--------------------------------

### Transfer files via CLI

Source: https://github.com/xspadex/openocto/blob/main/README.md

Sends a local file to a destination path on a remote machine.

```bash
octo send local gpu ~/data/dataset.tar.gz --dest /work/data/dataset.tar.gz
```

--------------------------------

### Worker Join Commands

Source: https://github.com/xspadex/openocto/blob/main/README.md

Commands to join a remote machine to the OpenOcto network, either directly or via SSH jump server.

```bash
pip install openocto
octo join --token "$(octo token)" --name gpu --tags "gpu,cuda"
```

```bash
# On a jump server that can SSH into the GPU machine:
octo join --token "..." --name gpu --tags "gpu,cuda" --ssh "user@gpu-internal-ip"
```

--------------------------------

### Architecture Diagram

Source: https://github.com/xspadex/openocto/blob/main/README.md

Visual representation of the communication flow between the agent, relay, and remote worker.

```text
┌──────────────┐         ┌───────────────┐         ┌──────────────┐
│  Your Agent  │  HTTP   │  Redis Relay  │  HTTP   │  Remote GPU  │
│ (Claude Code)│────────>│  (Upstash)    │<────────│ (octo daemon)│
│              │         │  serverless   │         │              │
│ MCP / CLI    │         │  free tier    │         │  any machine │
└──────────────┘         └───────────────┘         └──────────────┘
```
Tokens:
Raw