Skip to main content

Chapter 9: The aip.json Schema

TL;DR​

The aip.json file is the manifest that describes your pack to the Worka host. Here is a minimal example:

{
  // --- Identity ---
  "tenant": "my-github-username",
  "name": "my-cool-pack",
  "version": "0.1.0",

  // --- Presentation ---
  "display_name": "My Cool Pack",
  "description": "Automation for property operations",

  // --- Permissions & Dependencies ---
  "capabilities": ["net.access"],
  "dependencies": ["worka/contacts"],

  // --- Optional Views ---
  "views": {
    "home": { "title": "Dashboard" }
  }
}

Every pack requires an aip.json file in its root directory. This manifest acts as a contract between your pack and the Worka Host, providing all the metadata needed to build, run, and display your pack correctly.

Let's break down the key sections of the file.

Root Properties: Identity and Presentation​

These fields define the core identity of your pack and how it appears in the Worka UI.

  • tenant (string, required): A unique namespace, like a publisher ID. Your GitHub username is a good choice.
  • name (string, required): The machine-readable name of the pack (e.g., my-cool-pack).
  • version (string, required): The version of your pack, following Semantic Versioning (e.g., 0.1.0).
  • display_name (string, required): The human-readable name shown in the UI (e.g., "My Cool Pack").
  • description (string, required): A brief description of what your pack does.
  • author (string, optional): The name and/or email of the pack author.

Backend Logic​

Worka v2 packs expose a single MCP server inside the pack. You do not declare multiple servers or Docker images in the manifest. The host discovers tools directly from the pack’s WASM.

User Interface: views​

The views section is optional. Views can be:

  • Static: returned by init_views (recommended for default pages).
  • Dynamic: returned in worka_ui responses for tool calls.

Security and Dependencies​

These fields define your pack's relationship with the host and other packs.

  • capabilities (array of strings): permissions your pack requires (e.g. "net.access").
  • dependencies (array of strings): packs this pack can call (e.g. "worka/contacts").