@hybrd/cli

The hybrid / hy command-line tool for building, developing, deploying, and managing Hybrid AI agents.

Installation

npm install -g @hybrd/cli
# or use directly via npx
npx hybrid <command>

Commands

hybrid init [name]

Initialize a new agent project with an interactive setup:

hybrid init          # Interactive mode
hybrid init my-agent # Skip name prompt

The init command will ask:

1. Project name - Directory name for the project
2. Agent display name - Human-readable name for the agent
3. Deployment target - Fly.io, Railway, Cloudflare, AWS, or GCP
4. Fly.io app name - App identifier (lowercase, numbers, hyphens)
5. Primary region - Closest region for deployment
6. VM size - Resource allocation (shared/performance CPU, RAM)
7. Persistent storage - Enable volume for data persistence
8. Storage size - Volume size in GB (if enabled)

Generated files:

my-agent/
├── package.json      # Project dependencies
├── SOUL.md           # Agent identity and behavior
├── AGENTS.md         # Repository guidelines
├── .env.example      # Environment variables template
├── .gitignore        # Git ignore rules
├── Dockerfile        # Container build instructions
├── fly.toml          # Fly.io deployment config
├── start.sh          # Start script
└── README.md         # Project documentation

hybrid build [--target]

Build the agent bundle into ./dist/:

hybrid build                  # Default build
hybrid build --target fly     # Fly.io target (default)
hybrid build --target spawn   # Spawn Sprite target
hybrid build --target railway # Railway target
hybrid build --target cf      # Cloudflare Workers target

The build:

1. Compiles packages/agent via pnpm --filter hybrid/agent build
2. Creates ./dist/ directory structure
3. Copies compiled dist/ from the agent package
4. Copies SOUL.md, AGENTS.md, and agent.ts from your project root
5. Copies core skills from packages/agent/skills/ → .hybrid/skills/core/
6. Copies user skills from ./skills/ → .hybrid/skills/ext/
7. Writes skills/skills_lock.json listing all installed skills
8. Generates deployment files: package.json, Dockerfile, fly.toml, start.sh

Build output structure:

dist/
├── dist/                    # Compiled agent code
│   ├── server/index.cjs     # Full Claude Code SDK server
│   ├── server/simple.cjs    # Lightweight server
├── skills/
│   ├── core/                # Built-in skills (memory)
│   ├── ext/                 # User-installed skills
│   └── skills_lock.json
├── package.json
├── Dockerfile
├── fly.toml                 # (Fly.io targets only)
├── spawn.sh                 # (Spawn targets only)
└── start.sh                 # Starts server

The build:

1. Compiles packages/agent via pnpm --filter hybrid/agent build
2. Creates ./dist/ directory structure
3. Copies compiled dist/ from the agent package
4. Copies SOUL.md, AGENTS.md, and agent.ts from your project root
5. Copies core skills from packages/agent/skills/ → .hybrid/skills/core/
6. Copies user skills from ./skills/ → .hybrid/skills/ext/
7. Writes skills/skills_lock.json listing all installed skills
8. Generates deployment files: package.json, Dockerfile, fly.toml, start.sh

Build output structure:

dist/
├── dist/                    # Compiled agent code
│   ├── server/index.cjs     # Full Claude Code SDK server
│   ├── server/simple.cjs    # Lightweight server
├── skills/
│   ├── core/                # Built-in skills (memory)
│   ├── ext/                 # User-installed skills
│   └── skills_lock.json
├── package.json
├── Dockerfile
├── fly.toml                 # (Fly.io targets only)
├── spawn.sh                 # (Spawn targets only)
└── start.sh                 # Starts server

hybrid dev

Start the development server. Builds the agent then runs pnpm dev in the agent directory:

hybrid dev

hybrid deploy [platform]

Build then deploy to a platform:

hybrid deploy          # Deploys to Fly.io (default)
hybrid deploy          # Fly.io: runs `fly deploy` from .hybrid/
hybrid deploy cf       # Cloudflare: builds packages/gateway, runs `wrangler deploy`
hybrid deploy railway  # Railway (builds only, manual deploy)

hybrid register

Register the agent identity:

hybrid register

hybrid install <source>

Install a skill into your agent project:

# From GitHub
hybrid install github:username/repo
hybrid install github:username/repo/path/to/skill

# From npm
hybrid install @scope/skill-package

# From local path
hybrid install ./path/to/skill

Skills are directories containing a SKILL.md file with YAML frontmatter (name, description). Installed skills are copied to ./skills/ and tracked in skills-lock.json.

hybrid uninstall <name>

Remove an installed skill:

hybrid uninstall my-skill-name

hybrid skills

List all available skills:

hybrid skills

Shows core skills (from packages/agent/skills/) and installed extension skills (from ./skills/), with name and description from each SKILL.md.

Generated Files

Dockerfile (Fly.io / Railway)

FROM node:20
WORKDIR /app
COPY dist/ ./dist/
COPY skills/ ./skills/
COPY package.json .
COPY start.sh .
COPY SOUL.md .
COPY AGENTS.md .
RUN npm install
CMD ["sh", "start.sh"]

start.sh

Runs the agent server:

node dist/server/simple.cjs

fly.toml

Generated for Fly.io targets with appropriate service configuration.

Skills System

Skills are markdown-based tool definitions. Each skill is a directory with:

my-skill/
└── SKILL.md      # Required: YAML frontmatter + markdown content

SKILL.md frontmatter:

---
name: my-skill
description: What this skill does
---

Skills are injected into the agent's system prompt, describing tools and capabilities the LLM can use.

Skill sources:

| Source | Format | Example | |--------|--------|---------| | GitHub | github:user/repo[/path] | github:acme/skills/web-search | | npm | @scope/pkg or pkg-name | @acme/weather-skill | | Local | ./relative/path | ./skills/my-tool |

Build Pipeline

hybrid build
    │
    ├── pnpm --filter hybrid/agent build
    │
    ├── Create .hybrid/
    │
    ├── Copy dist/ → .hybrid/dist/
    │
    ├── Copy SOUL.md, AGENTS.md, agent.ts
    │
    ├── Copy core skills → .hybrid/skills/core/
    │
    ├── Copy ./skills/ → .hybrid/skills/ext/
    │
    ├── Write skills_lock.json
    │
    └── Generate: package.json, Dockerfile, fly.toml, start.sh

hybrid deploy
    │
    ├── hybrid build --target fly
    │
    └── fly deploy (from .hybrid/)

hybrid deploy cf
    │
    ├── pnpm --filter hybrid/gateway build
    │
    └── wrangler deploy (from packages/gateway/)

Relation to Other Packages

• Builds packages/agent via pnpm --filter
• Deploys packages/gateway for Cloudflare Workers target
• Delegates register command to agent identity scripts
• The output .hybrid/ directory is what packages/gateway runs inside its Docker container

License

MIT