Manifest

The manifest is the contract that defines a Trik. It declares how the trik operates as an agent, what tools it provides, and what constraints apply to its outputs.

Anatomy of a Manifest

Every Trik has a manifest.json at its root:


{
  "schemaVersion": 2,
  "id": "article-search",
  "name": "Article Search",
  "description": "Searches for articles on a given topic.",
  "version": "2.0.0",
 
  "agent": { ... },
  "tools": { ... },
  "capabilities": { ... },
  "limits": { ... },
  "entry": { ... }
}

Core Fields

Identification

Field	Required	Description
`schemaVersion`	Yes	Must be `2`
`id`	Yes	Unique identifier (lowercase, alphanumeric + dashes)
`name`	Yes	Human-readable name
`description`	Yes	What this Trik does
`version`	Yes	Semantic version

Entry Point

The entry field tells the gateway how to run your Trik:


{
  "entry": {
    "module": "./dist/index.js",
    "export": "default",
    "runtime": "node"
  }
}

module - Path to the compiled JavaScript file (relative to trik directory)
export - Named export or "default"
runtime - Optional: "node" (default) or "python"

Agent

The agent block is the core of a v2 manifest. It declares how the trik operates.


{
  "agent": {
    "mode": "conversational",
    "handoffDescription": "Search for articles on any topic. Finds relevant articles, provides summaries, and can retrieve full content.",
    "systemPromptFile": "./system-prompt.md",
    "model": {
      "provider": "anthropic",
      "capabilities": ["tool_use"],
      "temperature": 0.3
    },
    "domain": ["content search", "article curation"]
  }
}

Agent Fields

Field	Required	Description
`mode`	Yes	`"conversational"` or `"tool"`
`handoffDescription`	Conversational only	Description used to generate the handoff tool for the main agent (10-500 chars)
`systemPrompt`	Conversational only	Inline system prompt
`systemPromptFile`	Conversational only	Path to system prompt file (mutually exclusive with `systemPrompt`)
`model`	No	LLM model preferences
`domain`	Yes	String array of domain tags describing this agent’s expertise

Mode: Conversational

Conversational triks are full LLM agents. The main agent hands off the conversation by calling a talk_to_<trik_id> tool. The trik processes messages, uses its own tools, and calls transfer_back when done.

Requires: handoffDescription and either systemPrompt or systemPromptFile.

Mode: Tool

Tool-mode triks export native tools directly to the main agent. There is no handoff, no LLM inside the trik, and no session state. The main agent calls the tools as if they were its own.

Requires: at least one tool in the tools block with inputSchema, outputSchema, and outputTemplate.

Tools

The tools block declares the tools your trik provides. The structure differs based on the agent mode.

Conversational Mode Tools

For conversational triks, tools are used internally by the trik’s LLM agent. The manifest declares metadata for logging and quality scoring — runtime schemas live in code.


{
  "tools": {
    "searchArticles": {
      "description": "Search for articles by topic",
      "logTemplate": "Searched for {{topic}} — found {{count}} results",
      "logSchema": {
        "topic": { "type": "string", "enum": ["AI", "technology", "science", "health"] },
        "count": { "type": "integer", "minimum": 0 }
      }
    }
  }
}

Field	Required	Description
`description`	Yes	What this tool does
`logTemplate`	No	Template for log entries. Placeholders: `{{field}}`
`logSchema`	No	Schema for log template placeholder values (must use constrained types)

The logTemplate and logSchema pair controls what the main agent sees after a handoff completes. The gateway fills the template with validated values to produce a structured session summary.

Tool Mode Tools

For tool-mode triks, the manifest declares the full runtime contract — input/output schemas and the output template.


{
  "tools": {
    "getWeather": {
      "description": "Get current weather for a city",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "minLength": 1 }
        },
        "required": ["city"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "temperature": { "type": "integer" },
          "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] },
          "condition": { "type": "string", "enum": ["sunny", "cloudy", "rainy", "snowy"] }
        },
        "required": ["temperature", "unit", "condition"]
      },
      "outputTemplate": "Current weather: {{temperature}}{{unit}}, {{condition}}"
    }
  }
}

Field	Required	Description
`description`	Yes	What this tool does
`inputSchema`	Yes (tool mode)	JSON Schema for the tool’s input
`outputSchema`	Yes (tool mode)	JSON Schema for the tool’s output (must use agent-safe types)
`outputTemplate`	Yes (tool mode)	Template for output text the main LLM sees. Placeholders: `{{field}}`

The outputSchema enforces that all string properties use constrained types (enum, format, or pattern). The outputTemplate is filled with validated, property-stripped values — the main agent only ever sees this formatted text.

Capabilities

Capabilities declare what resources and permissions your trik needs. They are cross-checked against source code by the scanner — undeclared capabilities block publishing, and mismatches produce warnings at install time.

Session

Enable cross-turn memory for conversational triks. The gateway creates and manages sessions based on these settings.


{
  "capabilities": {
    "session": {
      "enabled": true,
      "maxDurationMs": 1800000
    }
  }
}

Field	Default	Description
`enabled`	—	Required. Enable session support
`maxDurationMs`	1800000	Session timeout in ms (default: 30 minutes)

Storage

Enable persistent key-value storage. The gateway provides scoped storage and enforces size quotas.


{
  "capabilities": {
    "storage": {
      "enabled": true,
      "maxSizeBytes": 10485760,
      "persistent": true
    }
  }
}

Field	Default	Description
`enabled`	—	Required. Enable persistent storage
`maxSizeBytes`	104857600	Max storage size in bytes (default: 100MB)
`persistent`	true	Whether storage persists across sessions

Filesystem

Enable sandboxed file access. Triks declaring this capability run inside a Docker container with a mounted /workspace directory.


{
  "capabilities": {
    "filesystem": {
      "enabled": true,
      "maxSizeBytes": 524288000
    }
  }
}

Field	Default	Description
`enabled`	—	Required. Enable filesystem access
`maxSizeBytes`	524288000	Max workspace size in bytes (default: 500MB)

Shell

Enable command execution inside the container. Requires filesystem to also be enabled. Allows triks to run processes, start dev servers, and expose ports.


{
  "capabilities": {
    "shell": {
      "enabled": true,
      "timeoutMs": 30000,
      "maxConcurrent": 3,
      "exposePorts": [3000]
    }
  }
}

Field	Default	Description
`enabled`	—	Required. Enable shell command execution
`timeoutMs`	30000	Max time per command in ms
`maxConcurrent`	3	Max concurrent processes
`exposePorts`	—	Ports to expose from container to host (e.g., `[3000]` for dev servers). Ports below 1024 are blocked at runtime.

Trik Management

Allow the trik to search, install, uninstall, and upgrade other triks. The gateway injects a registry context only when this capability is declared. Users are warned about this capability during install.


{
  "capabilities": {
    "trikManagement": {
      "enabled": true
    }
  }
}

Field	Default	Description
`enabled`	—	Required. Enable trik management

Limits

Safety constraints on execution:


{
  "limits": {
    "maxTurnTimeMs": 5000
  }
}

Field	Description
`maxTurnTimeMs`	Maximum time per turn before timeout

Configuration

Declare configuration requirements (API keys, tokens, etc.):


{
  "config": {
    "required": [
      { "key": "NEWS_API_KEY", "description": "API key for the news service" }
    ],
    "optional": [
      { "key": "DEFAULT_LANGUAGE", "description": "Default language for results", "default": "en" }
    ]
  }
}

Configuration values are managed through the CLI (trikhub config set) and passed to trik code via the context.config object.

Full Examples

Conversational Trik Manifest


{
  "schemaVersion": 2,
  "id": "article-search",
  "name": "Article Search",
  "description": "Searches for articles on a given topic.",
  "version": "2.0.0",
 
  "agent": {
    "mode": "conversational",
    "handoffDescription": "Search for articles on any topic. Finds relevant articles, provides summaries, and can retrieve full content.",
    "systemPromptFile": "./system-prompt.md",
    "model": {
      "provider": "anthropic",
      "capabilities": ["tool_use"],
      "temperature": 0.3
    },
    "domain": ["content search", "article curation"]
  },
 
  "tools": {
    "searchArticles": {
      "description": "Search for articles by topic",
      "logTemplate": "Searched for '{{topic}}' — found {{count}} results",
      "logSchema": {
        "topic": { "type": "string", "maxLength": 50 },
        "count": { "type": "integer", "minimum": 0 }
      }
    },
    "getArticle": {
      "description": "Get full article content by ID",
      "logTemplate": "Retrieved article {{articleId}}",
      "logSchema": {
        "articleId": { "type": "string", "format": "id" }
      }
    }
  },
 
  "capabilities": {
    "session": { "enabled": true, "maxDurationMs": 1800000 },
    "storage": { "enabled": true, "maxSizeBytes": 10485760 }
  },
 
  "limits": { "maxTurnTimeMs": 10000 },
 
  "entry": {
    "module": "./dist/index.js",
    "export": "default"
  },
 
  "config": {
    "required": [
      { "key": "NEWS_API_KEY", "description": "API key for the news service" }
    ]
  }
}

Tool Mode Trik Manifest


{
  "schemaVersion": 2,
  "id": "weather-tools",
  "name": "Weather Tools",
  "description": "Get current weather and forecasts for any city.",
  "version": "1.0.0",
 
  "agent": {
    "mode": "tool",
    "domain": ["weather", "forecasting"]
  },
 
  "tools": {
    "getWeather": {
      "description": "Get current weather for a city",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "minLength": 1 }
        },
        "required": ["city"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "temperature": { "type": "integer" },
          "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] },
          "condition": { "type": "string", "enum": ["sunny", "cloudy", "rainy", "snowy", "windy"] }
        },
        "required": ["temperature", "unit", "condition"]
      },
      "outputTemplate": "Current weather in requested city: {{temperature}} {{unit}}, {{condition}}"
    }
  },
 
  "limits": { "maxTurnTimeMs": 3000 },
 
  "entry": {
    "module": "./dist/index.js",
    "export": "default"
  },
 
  "config": {
    "required": [
      { "key": "WEATHER_API_KEY", "description": "API key for the weather service" }
    ]
  }
}

Next: Learn about Agent Modes to understand conversational vs tool mode.