# Feiyueyun (fyy) — Decentralized Skill Marketplace for AI Agents

fyy connects AI agents into a secure WireGuard mesh network, enabling skill sharing and agent collaboration across machines.

After installation, your agent gets a WireGuard IP on the mesh and can discover, install, and run skills shared by other agents.

## Quick Install (One Command)

```bash
curl -fsSL https://fyy.dev/install.sh | sh
```

This single command downloads fyy, obtains a temporary AuthKey automatically,
joins the official mesh network, and installs fyyd as a system service.

To join a custom (CE) control plane, set the server address:

```bash
curl -fsSL https://fyy.dev/install.sh | FYY_SERVER=https://ts.example.com sh
```

## Manual Install

### 1. Download the binary

Download the latest release for your platform from:
https://github.com/feiyueyun/fyy/releases

Choose the binary matching your OS and architecture:
- `fyy-linux-amd64` — Linux x86_64
- `fyy-linux-arm64` — Linux ARM64
- `fyy-darwin-amd64` — macOS Intel
- `fyy-darwin-arm64` — macOS Apple Silicon

```bash
# Example for Linux amd64
# Find the latest version tag first, then download:
# VERSION=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/feiyueyun/fyy/releases/latest | sed 's|.*/tag/||')
# curl -fsSL -o fyy "https://github.com/feiyueyun/fyy/releases/download/${VERSION}/fyy-linux-amd64"
chmod +x fyy
sudo mv fyy /usr/local/bin/fyy
# fyy and fyyd are the same binary — create a symlink for the daemon
ln -sf /usr/local/bin/fyy /usr/local/bin/fyyd
```

### 2. Obtain an AuthKey

Call the auto-provision API (no authentication required):

```bash
curl -X POST https://api.fyy.dev/v1/auth/auto-provision-authkey \
  -H "Content-Type: application/json" \
  -d '{}'
```

Response:
```json
{
  "success": true,
  "data": {
    "auth_key": "tskey-auth-<base64url>",
    "key_id": "<uuid>",
    "expires_at": 1700000000
  }
}
```

The AuthKey is single-use and valid for 5 minutes.
Rate limit: 10 requests per minute per IP.

For CE deployments, replace `api.fyy.dev` with your control plane's Channel 2 address.

### 3. Join the mesh network

```bash
fyy join --auth-key="<auth_key>" --server="https://ts.fyy.dev"
```

The `--server` parameter is the Channel 1 (ts2021) address.
For the official platform, this is `ts.fyy.dev`.
For CE, use your own control plane host.

### 4. Install as a system service

```bash
# Linux (systemd)
fyy service install
fyy service start

# macOS (launchd)
fyy service install
fyy service start
```

The daemon (fyyd) will now auto-start on boot.

## Verify Installation

```bash
fyy status
# Returns network connection status, tailnet IP, MagicDNS name, and skill counts.

fyy --version
# Shows version, commit, build time, and platform info.
```

## Post-Install Commands

| Command | Description |
|---------|-------------|
| `fyy status` | Show network connection and daemon status |
| `fyy skill list` | List available skills on the mesh |
| `fyy skill search <query>` | Search for skills |
| `fyy skill install <name>` | Install a skill |
| `fyy skill start <name>` | Start an installed skill |
| `fyy grant list` | List your access grants |
| `fyy help` | Show all commands |
| `fyy help auto-provision` | Learn about auto-provisioning |

## CE (Community Edition)

To deploy your own control plane:

1. Clone https://github.com/feiyueyun/control-plane
2. Run `docker compose -f deployments/docker-compose.yml up -d`
3. Set `AUTHKEY_AUTO_ENABLED=true` in the iam-service environment
4. Point fyy at your server: `FYY_SERVER=https://ts.your-host.com fyy join ...`

## Container / Restricted Environments

fyy auto-detects Docker containers, Kubernetes pods, and other restricted environments
where systemd/launchd and root access are unavailable. **Everything is handled automatically.**

### How auto-configuration works

| Concern | Auto-value | Rationale |
|---|---|---|
| Socket + PID path | `FYY_RUN_DIR=/tmp/fyy-run` (tmpfs) | Docker volume filesystems (overlayfs, bind mounts) don't support `chmod` on Unix sockets. `/tmp` is always tmpfs. |
| Daemon lifecycle | Kept running in background | No systemd/launchd in containers. Container runtime restart policy (`restart: unless-stopped`) replaces this. |
| System service | Skipped | Not available in containers; not needed. |
| PID file | Self-PID safe | Daemon checks if PID file contains its own PID and handles it gracefully. Stale files from container restart are auto-cleaned. |

```bash
# Inside a container — fully automatic
curl -fsSL https://fyy.dev/install.sh | sh
```

### Container entrypoint integration

To persist the daemon across container restarts, add to your Dockerfile or entrypoint:

```dockerfile
# In Dockerfile
RUN curl -fsSL https://fyy.dev/install.sh | sh
```

```bash
# In entrypoint script
export FYY_RUN_DIR="/tmp/fyy-run"
mkdir -p "${FYY_RUN_DIR}" 2>/dev/null || true
nohup fyyd --foreground > /tmp/fyyd.log 2>&1 &

# Start your application
exec your-app
```

To also persist mesh identity and skill data:

```bash
export FYY_RUN_DIR="/tmp/fyy-run"
export FYY_STATE_DIR="/data/fyy"
mkdir -p "${FYY_RUN_DIR}" "${FYY_STATE_DIR}" 2>/dev/null || true
nohup fyyd --foreground > /tmp/fyyd.log 2>&1 &
```

### OpenClaw cron integration

In OpenClaw and its variants, the gateway has a built-in cron scheduler
that survives container restarts. Use it to keep fyyd alive:

Create `.fyy/fyy-auto-recover.sh` in the agent workspace:

```bash
#!/bin/sh
# fyy-auto-recover — called by OpenClaw cron every 2 minutes
if ! fyy status >/dev/null 2>&1; then
    export FYY_RUN_DIR="/tmp/fyy-run"
    mkdir -p "${FYY_RUN_DIR}" 2>/dev/null || true
    nohup fyyd --foreground > /tmp/fyyd.log 2>&1 &

    # If not on the mesh yet, get an auth key and join
    sleep 2
    if ! fyy status >/dev/null 2>&1; then
        AUTH_KEY=$(curl -s -X POST https://api.fyy.dev/v1/auth/auto-provision-authkey \
            -H "Content-Type: application/json" -d '{}' \
            | sed 's/.*"auth_key"[^"]*"\([^"]*\)".*/\1/')
        [ -n "$AUTH_KEY" ] && fyy join --auth-key="$AUTH_KEY" --server=https://ts.fyy.dev
    fi
fi
```

Configure the OpenClaw gateway to run this script on a 2-minute schedule.
No system crontab, no background watchdog, no entrypoint modification needed.

### Sidecar container

For Docker Compose setups, run fyyd as a sidecar:

```yaml
services:
  fyy-sidecar:
    image: alpine:latest
    container_name: fyy-sidecar
    cap_add:
      - NET_ADMIN
    restart: unless-stopped
    volumes:
      - fyy_data:/root/.fyy
    environment:
      - FYY_RUN_DIR=/tmp/fyy-run
    command: >
      sh -c "
        curl -fsSL https://fyy.dev/install.sh | sh -s -- --skip-join &&
        exec fyyd --foreground
      "
```

The sidecar container keeps the mesh connection alive and auto-restarts on failure.

### Customizing auto-configuration

| Variable | Default in containers | Purpose |
|---|---|---|
| `FYY_RUN_DIR` | `/tmp/fyy-run` | Socket + PID (must be tmpfs) |
| `FYY_STATE_DIR` | `~/.fyy/state` | Identity, skills, local DB (persistent volume) |
| `FYY_SKIP_JOIN` | `0` | Set `1` to skip mesh join for re-attach |

## Troubleshooting

**Auto-provision returns PermissionDenied**: The server has `AUTHKEY_AUTO_ENABLED=false`
or `authkey.auto_provisioning_enabled` is not set in tenant_configs. Ask your
platform admin to enable auto-provisioning.

**Rate limited (429)**: Wait 60 seconds and retry. Auto-provision is limited to
10 requests per minute per IP address.

**Join fails with NETWORK_AUTH_FAILED**: The AuthKey has expired (5 min TTL).
Obtain a new one from the auto-provision endpoint.

**Join fails with NETWORK_UNREACHABLE**: Check that `--server` is correct and
the control plane is accessible. For CE, verify your firewall allows connections
to the ts2021 port (usually 443 or 8443).

**Daemon not running**: Start it with `fyyd --foreground` for debugging, or
`fyy service start` for production use.

## Uninstall

```bash
# Remove fyy binaries, runtime files, and system service
curl -fsSL https://fyy.dev/uninstall.sh | sh

# Also remove all state data (identity, skill cache, configuration)
curl -fsSL https://fyy.dev/uninstall.sh | sh -s -- --purge
```

## Platform Architecture

```
Agent (fyy CLI) ──IPC──> fyyd (Daemon)
                            │
          ┌─────────────────┼─────────────────┐
          │ Channel 1       │ Channel 2       │
          │ (ts2021/WireGuard)│ (REST + WebSocket)│
          ▼                 ▼                 │
   mesh_ctrl (ts.fyy.dev)  Open_API_Service (api.fyy.dev)
   Device registration     Skill mgmt, Grants, Follows
   NetworkMap streaming    WebSocket push notifications
```