Skip to main content

​
Hub Files

HUB.yaml is the manifest file at the root of every Hubify workspace. It is the single source of truth — every connected agent reads it on startup. It defines the hub’s identity, connected agents, model routing, installed skills, vault configuration, and privacy settings.

​
Full HUB.yaml Example

hub:
  version: "2.0"
  id: "hub_abc123"
  name: "Houston's OS"
  owner: "houston"
  template: "myos"
  created: "2026-02-19T00:00:00Z"

# Intelligence layer configuration
intelligence:
  global: opt-in
  org: null

# Connected agents (auto-updated by hubify connect)
agents:
  - id: "agent_cloud"
    platform: "hubify-cloud"
    url: "https://houston.hubify.com"
    role: "orchestrator"
    active: true
  - id: "agent_local"
    platform: "openclaw-local"
    host: "macbook-air"
    role: "primary"
    active: false

# Memory configuration (Convex-backed, real-time)
memory:
  hub_id: "hub_abc123"
  retention_days: 365

# Reserved context files (auto-loaded by all agents)
context:
  reserved_files:
    - AGENTS.md
    - SOUL.md
    - USER.md
    - MEMORY.md
    - HEARTBEAT.md
  memory_dir: "./memory"
  learnings_dir: "./learnings"
  knowledge_dir: "./knowledge"

# Model routing
models:
  default: "anthropic/claude-sonnet-4-6"
  routing:
    orchestrator: "anthropic/claude-sonnet-4-6"
    researcher: "kimi/k2.5"
    automation: "google/gemini-flash"
  free_tier: ["kimi/k2.5", "google/gemini-flash"]
  byok:
    anthropic: { key_ref: "vault://keys/anthropic" }
    openai: { key_ref: "vault://keys/openai" }

# Tool vault
vault:
  id: "vault_abc123"

# Installed skills
skills:
  registry: "hubify"
  installed:
    - { id: "strava", version: "1.2.3" }
    - { id: "github", version: "2.0.1" }
    - { id: "telegram-topics", version: "1.0.0" }

# Privacy settings
privacy:
  contribute_to_global: false
  vault_shared_across_workspaces: true

# Workspace mode
mode: "guided"   # guided | power | open

​
Key Sections

​
Hub Identity

hub:
  version: "2.0"
  id: "hub_abc123"         # Assigned by Hubify on creation
  name: "Houston's OS"
  owner: "houston"
  template: "myos"
  created: "2026-02-19T00:00:00Z"
The id is assigned during workspace provisioning. The template field records which template was used to create the workspace.

​
Agents

agents:
  - id: "agent_cloud"
    platform: "hubify-cloud"
    url: "https://houston.hubify.com"
    role: "orchestrator"
    active: true
  - id: "agent_local"
    platform: "openclaw-local"
    host: "macbook-air"
    role: "primary"
    active: false
The agents list is auto-updated when you run hubify connect. Each entry represents a connected agent instance — cloud, local, or any platform (Claude Code, Cursor, etc.).

​
Model Routing

models:
  default: "anthropic/claude-sonnet-4-6"
  routing:
    orchestrator: "anthropic/claude-sonnet-4-6"
    researcher: "kimi/k2.5"
    automation: "google/gemini-flash"
    reviewer: "anthropic/claude-haiku-4-5"
  free_tier: ["kimi/k2.5", "google/gemini-flash"]
  byok:
    anthropic: { key_ref: "vault://keys/anthropic" }
    openai: { key_ref: "vault://keys/openai" }
HUB.yaml is the single authority for model routing. No more per-platform configuration confusion. The free_tier models are available without API keys on the Starter plan. BYOK (bring your own key) models reference the encrypted vault.

​
Intelligence Configuration

intelligence:
  global: opt-in
  org: null

privacy:
  contribute_to_global: false
  vault_shared_across_workspaces: true
Controls how the workspace participates in the Intelligence Network. See The Intelligence Network for details.

​
Workspace Mode

mode: "guided"   # guided | power | open
ModeReserved StructureTemplate ActiveSkills Pre-installedTarget
GuidedOnYesYesNew users
PowerOnUser customizesUser choosesBuilders
OpenOffOffOffAdvanced users
Mode is toggleable at any time. Nothing is deleted when switching.

​
Reserved File Structure

Every workspace using Guided or Power mode follows this structure: 
workspace/
  HUB.yaml              # Manifest
  AGENTS.md              # Agent instructions
  SOUL.md                # Identity / persona
  USER.md                # User profile
  MEMORY.md              # Long-term curated memory
  HEARTBEAT.md           # Proactive checklist
  PROJECTS.md            # Project index (auto-generated)
  TASKS.md               # Task index (read-only, rendered from API)
  LEARNINGS.md           # Learnings index (auto-updated)
  KNOWLEDGE.md           # Knowledge base index

  .hub/                  # Runtime state (gitignored)
    agents.json
    sync.log
    cache/

  memory/                # Episodic memory
    YYYY-MM-DD.md

  skills/                # Installed skills
    skill-name/
      SKILL.md

  knowledge/             # Curated knowledge base
    topic-name.md
    INDEX.md

  learnings/             # Extracted learnings
    YYYY-MM-DD.md
    INDEX.md

  projects/              # User space

  vault/                 # Encrypted credentials (gitignored)
    .vault.enc
TASKS.md is read-only and auto-generated from the Convex task store. Agents write tasks to the API, not to the file. The file regenerates on every sync.

​
.hub Skill Files

In addition to the workspace HUB.yaml, individual skills use the .hub file format with YAML frontmatter and Markdown body: 
---
name: api-error-handling
version: 1.0.0
type: skill
human_editable: false

trust:
  confidence: 0.89
  executions: 4231

integrity:
  manifest_hash: "sha256:abc123..."
  all_files_present: true

lineage:
  - version: "1.0.0"
    date: "2026-01-01"
    evolved_from: "initial creation"
---

# API Error Handling

Instructions for handling API errors...

​
Validation Rules

RuleDescription
Name formatLowercase, hyphens, starts with letter
Version formatSemantic versioning (X.Y.Z)
TypeMust be skill, agent, or soul
human_editableMust be false for the public registry
Manifest hashMust match file contents

​
CLI Commands

# Create HUB.yaml in current directory
hubify init

# Create a .hub skill file
hubify hub init --type skill

# Validate a .hub file
hubify hub validate my-skill.hub

# Update version
hubify hub update my-skill.hub --bump patch

# View file info
hubify hub info my-skill.hub

# Report execution
hubify hub report my-skill --result success

# Check evolution status
hubify hub evolve my-skill

Skills

Skills that use the .hub format

Trust Metrics

How trust data is stored in .hub files