wrapd.yaml

The wrapd.yaml file defines the endpoints your agent exposes. The agent reads this file on startup and registers the endpoints with Wrapd.

Minimal example

version: 1
endpoints:
  - name: hello
    method: GET
    command: echo
    args:
      - name: name
        default: "world"

Full example

version: 1
endpoints:
  - name: deploy
    method: POST
    description: "Deploy to staging"
    command: /ops/deploy.sh
    args:
      - name: branch
        required: true
      - name: environment
        required: false
        default: "staging"
    timeout: 120
    working_dir: /var/app
    transformer:
      type: json

Top-level fields

Field	Type	Required	Description
version	integer	Yes	Must be 1
agent_version	string	No	Pin to a specific agent release. The agent logs a warning on startup if the running version doesn’t match.
endpoints	array	Yes	At least one endpoint required

Endpoint fields

Field	Type	Required	Default	Description
name	string	Yes	—	Endpoint slug, must be unique. Becomes the URL path segment.
method	string	Yes	—	HTTP method: GET, POST, PUT, DELETE, PATCH
description	string	No	—	Human-readable description shown in the dashboard
command	string	Yes	—	The CLI command to execute
args	array	No	—	Argument definitions
timeout	integer	No	60	Max execution time in seconds (1–3600). Process is killed and returns exit code 124 on timeout. Free tier: max 60s. Pro: max 1800s. Team: max 3600s.
working_dir	string	No	—	Working directory for the command
public	boolean	No	false	If true, endpoint is callable without an API key. See Public Endpoints.
trigger	string	No	http	http (default) or webhook. See Webhook Triggers.
async	boolean	No	true	Webhook mode only. If true, returns 202 immediately. If false, waits for output.
secret	string	No	—	Webhook mode only. Env var reference (e.g. $GITHUB_WEBHOOK_SECRET) for HMAC-SHA256 verification.
transformer	object	No	—	Output transformation. See Transformers.

Argument fields

Field	Type	Required	Default	Description
name	string	Yes	—	Argument name, used as the key in API requests
required	boolean	No	false	If true, the argument must be provided by the caller
default	string	No	—	Default value when not provided

How arguments work

Arguments are passed to the command in order. When a caller makes a request, provided values override defaults.

args:
  - name: host
    required: true
  - name: count
    required: false
    default: "3"

Calling with {"host": "google.com"} runs: command google.com 3

Calling with {"host": "google.com", "count": "5"} runs: command google.com 5

If a required argument is missing, the execution returns an error.

Validation rules

• version must be 1
• At least one endpoint is required
• Endpoint names must be unique
• command cannot be empty
• method must be a valid HTTP verb