---
title: "Install Bundle"
method: POST
path: "/v1/bundles/install"
tags: ["v1", "protected", "bundles"]
---

# Install Bundle

`POST /v1/bundles/install`

Install a canonical bundle: MCP instances, skills, agents and automations.

## Request body

- InstallRequest — Install a (previously analyzed, possibly edited) canonical bundle.
  - `bundle` BundleInput, required — The canonical, fully-inlined package object.
    - `agents` BundleAgent[]
      - `instruction` string
      - `key` string, required
      - `mcps` string[] — BundleMcp keys to attach as tools.
      - `model` string, nullable
      - `name` string, required
      - `skills` string[] — BundleSkill keys to attach.
    - `automations` BundleAutomation[]
      - `agent` string, required — BundleAgent key to invoke.
      - `cron` string, required — 5- or 6-field cron expression.
      - `enabled` boolean
      - `key` string, required
      - `prompt` string, required — Task query passed to the agent on each run.
      - `timezone` string
      - `type` 'cron'
    - `channels` BundleChannel[]
      - `agent` string, required — BundleAgent key that handles inbound messages.
      - `bindings` object — Maps a credential the channel needs to a ${setup.x} reference, e.g. {'bot_token': '${setup.telegram_bot_token}'}.
      - `enabled` boolean
      - `key` string, required
      - `name` string, required — Display name for the created channel trigger.
      - `prompt` string — Task query template used for each inbound message.
      - `type` 'telegram' — Channel provider. Only Telegram in v0.1.0.
    - `description` string
    - `display_name` string, nullable
    - `mcps` BundleMcp[]
      - `bindings` object — Maps an env var / header name the server needs to a ${setup.x} reference, e.g. {'GITHUB_TOKEN': '${setup.github_token}'}.
      - `json_spec` object, required — Native MCP runtime spec. Must include 'type' (command|docker|url).
      - `key` string, required — In-package reference key (agents point at this).
      - `name` string, required — Instance display name created in the workspace.
    - `metadata` BundleMetadata — Marketplace presentation metadata (parity with plugin/app listings).
      - `capabilities` string[] — e.g. ["interactive", "write"].
      - `category` string, nullable
      - `developer` string, nullable — Publisher name.
      - `icon` string, nullable — Icon URL or asset reference.
      - `privacy_url` string, nullable
      - `terms_url` string, nullable
      - `website` string, nullable
    - `name` string, required — Stable package identifier (idempotency key).
    - `policies` BundlePolicy[]
      - `condition` string, nullable — Optional CEL condition.
      - `effect` 'allow' | 'deny' | 'cap' | 'approval' | 'safety', required
      - `enabled` boolean
      - `key` string, required
      - `message` string, nullable — Human-readable reason.
      - `params` object — Effect-specific params, e.g. {amount_usd, period} for cap.
      - `priority` integer
      - `subject` string — "workspace" or a BundleAgent key the rule binds to.
      - `target` string, required — Selector, e.g. "tool:send_email", "spend", "content", "*".
    - `schema_version` string
    - `setup` SetupField[]
      - `default` unknown
      - `help` string, nullable — Help text shown beneath the field.
      - `key` string, required — Stable identifier referenced via ${setup.key}.
      - `label` string, required — Human-readable label rendered in the form.
      - `max` number, nullable — Upper bound for type='number'.
      - `min` number, nullable — Lower bound for type='number'.
      - `options` string[], nullable — Choices for type='select'.
      - `required` boolean
      - `type` 'secret' | 'string' | 'number' | 'boolean' | 'select' — Input widget / storage hint for a setup field.
    - `skills` BundleSkill[]
      - `content` string, nullable — SKILL.md markdown for source_type=content.
      - `key` string, required
      - `name` string, required
      - `source_type` 'content' | 'github'
      - `source_url` string, nullable — Repo URL for source_type=github.
  - `setup_values` object — Values for the bundle's setup fields, keyed by setup field key.

## Response `200`

Successful Response

- InstallResult
  - `bundle_name` string, required
  - `entities` InstalledEntity[]
    - `action` 'created' | 'reused' | 'skipped', required
    - `detail` string, nullable
    - `id` string, nullable — Created/reused entity id, when applicable.
    - `key` string, required
    - `kind` 'mcp' | 'skill' | 'agent' | 'channel' | 'automation' | 'policy', required
    - `name` string, required
  - `installed_bundle_id` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agentarea/apis/agentarea-api.md) · [All operations](https://skmtc.net/agentarea/apis/agentarea-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentarea/agentarea-api/versions/e3650e48373b/schema)