---

Status: stable v0.1.0. Git tags—not npm publication—are the distribution channel. Review the source before installation: a Pi skill can guide system and network changes.

Operational-evidence caveat. Independently recorded cold-boot and live runtime evidence is not published for v0.1.0. Validate lifecycle and recovery on your target; this release does not claim observed macOS, WSL2, reboot, or mobile-client behavior.

BASED ON https://www.youtube.com/watch?v=Yj51wXMwFwE&t=907s

Table of Contents

1. Prerequisites
2. Installation
3. Usage
4. Architecture
5. Features
6. Runtime Stack
7. Safety Boundaries
8. Verification and Recovery
9. Contributing and Contact
10. License

---

#Built With

---

#Prerequisites

The guided workflow discovers its runtime state before proposing changes. It installs runtime components only after the relevant approval; they are not bundled as npm dependencies.

(back to top)

#Installation

#Agent Skills-compatible CLIs

Copy or link skills/mobile-agent-orchestrator/ as mobile-agent-orchestrator/ under one of the host's supported skill roots. The generic contract is one directory per skill containing a SKILL.md; references remain relative to that file. The host discovers and activates the skill, but host-specific persistence, lifecycle, and slash-command behavior must not be inferred from this repository.

For OpenCode, use any supported location:

• Project: .opencode/skills/mobile-agent-orchestrator/SKILL.md or .agents/skills/mobile-agent-orchestrator/SKILL.md
• Global: ~/.config/opencode/skills/mobile-agent-orchestrator/SKILL.md or ~/.agents/skills/mobile-agent-orchestrator/SKILL.md
• Configured path: add the containing directory, for example skills: ["./skills"], then place the skill at ./skills/mobile-agent-orchestrator/SKILL.md

Start OpenCode from the relevant project and use its discovered-skill interface or a matching natural-language request. OpenCode may disable external skill directories through configuration; configured skill paths remain the explicit fallback. This is an Agent Skill, not an MCP server, and requires no MCP implementation.

#Pi

#Recommended: install stable v0.1.0 from Git

pi install git:github.com/egdev6/mobile-agent-orchestrator@v0.1.0

Git tags—not npm publication—are this project's distribution channel. The release tag is created by automation after a validated release pull request merges; see the release guide for the release conditions.

#Source-review or development option: install from a local checkout

1. Review this repository, especially the skill and its on-demand references.

2. Install the reviewed local package:

   pi install /absolute/path/to/mobile-agent-orchestrator
   

3. Start Pi from your normal working directory.

(back to top)

#Usage

Use the skill from an active Agent Skills-compatible session. For Pi, the existing activation command remains:

/skill:mobile-agent-orchestrator

A matching natural-language request, such as “set up a private mobile agent environment with Tailscale and Mosh,” can also load the skill. Follow the guided path rather than running an installation recipe out of order:

1. Detect: allow read-only platform and state checks; unsupported or unclear targets stop safely.
2. Decide: answer only real decision gates, including Tailscale placement, key setup, Moshi privacy, integrations, and notifications.
3. Approve: explicitly authorize each privileged, network, service, firewall, pairing, lifecycle, or reboot mutation before it happens.
4. Verify: collect non-sensitive checkpoints after each approved mutation and use the recovery guide when a check fails.

The skill is a human-supervised orchestrator, not an unattended installer. Platform detail lives in the platform matrix and guided install reference so the core workflow stays concise. Lifecycle and checkpoint semantics are host-specific; the skill does not promise that another CLI provides Pi's persistence behavior.

(back to top)

#Architecture

mobile-agent-orchestrator/
├── package.json
│   └── pi.skills: ./skills ──> Pi package discovery (preserved)
├── skills/mobile-agent-orchestrator/
│   ├── SKILL.md ────────────> activation contract, decision gates, safe orchestration
│   └── references/ ─────────> loaded on demand: platform, installation, recovery
├── scripts/validate-package.mjs
│   └── Node.js ESM validator ──> metadata, package contents, local Markdown links
└── .github/workflows/
    ├── ci.yml ──────────────> npm test on pull requests and main
    └── tag-release.yml ─────> validated, merged-PR-only stable Git tags

Pi discovers the package's skills/ directory through the pi.skills manifest. Other compatible CLIs discover the same skill through their own supported roots or configured paths. The SKILL.md file uses Agent Skills-compatible Markdown and YAML frontmatter; its references are deliberately loaded only when the workflow needs their detail. The validator and GitHub Actions verify the package and gate future tags, but they do not certify a live remote-agent deployment.

(back to top)

#Features

(back to top)

#Runtime Stack

The package implementation and the remote environment it orchestrates are separate layers.

Tailscale, OpenSSH, Mosh, Moshi, moshi-hook, Herdr, tmux, and platform lifecycle tooling are runtime dependencies installed by the guided workflow. They are not package-bundled npm dependencies, and their exact installation route is chosen from current signed vendor or platform documentation after approval.

(back to top)

#Safety Boundaries

• Never open public SSH access or add router port forwarding; constrain any listener before enabling it.
• Keep Tailscale SSH disabled for the Moshi/OpenSSH key-authentication route.
• For the full-Mosh Windows route, run Tailscale in exactly one location: WSL, not Windows and WSL together. On macOS, use macOS as the single location.
• Do not place private keys, pairing tokens, sign-in URLs, QR data, or credentials in chat, shell history, or repository files. QR data is temporary secret material.
• Require explicit approval before privileged installation, authentication or firewall changes, cloud pairing, service/task creation, reboot, or destructive rollback.
• Preserve a local recovery path, validate SSH configuration before reload, test a second key-authenticated session, and record non-sensitive rollback evidence.

(back to top)

#Verification and Recovery

After each approved mutation, the workflow captures non-sensitive evidence for the private overlay, key-authenticated SSH, Mosh reconnection, session host, checkpoints, integrations, and notifications. A missing component or failed check is a finding—not authorization to make another change.

Before an approved reboot, the guide states that live processes will die, confirms recovery and rollback paths, then checks the actual post-reboot state. Herdr and tmux do not preserve live processes across a physical reboot. A host may provide its own persisted checkpoint or resume mechanism; only Pi's supported JSONL behavior is described here, and no equivalent is claimed for other CLIs. Independently recorded cold-boot and live runtime evidence is not published for v0.1.0, so validate lifecycle and recovery on your target.

Read the full verification and recovery guide before applying lifecycle or rollback changes.

(back to top)

#Contributing and Contact

• Contributing — focused changes, test expectations, and release-PR rules.
• Release guide — Git-tag distribution and stable-release guardrails.
• Security policy — report vulnerabilities privately; never include secrets in an issue.
• Issue tracker — report non-sensitive bugs and feature requests.

(back to top)

#License

Distributed under the MIT License.

(back to top)