1. Docs
  2. Reference
  3. REST API Docs
  4. Deployment Runners

Deployment Runners

    Deployment Runners execute Pulumi deployments in private, controlled environments. The Deployment Runners API allows you to manage agent pools, which are groups of deployment runners that handle Pulumi operations for your organization.

    List Org Agent Pool

    ▼
    GET /api/orgs/{orgName}/agent-pools

    Returns all agent pools configured for an organization. Agent pools enable self-hosted deployment agents, allowing organizations to run Pulumi Deployments on their own infrastructure for accessing private networks, meeting compliance requirements, or using custom execution environments. Each pool in the response includes its ID, name, and configuration details.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK
    Schema: ListAgentPoolsResponse
    • agentPools array[AgentPool] required
      The list of agent pools
    • ↳ created integer required
      Unix epoch timestamp (seconds) when the agent pool was created.
    • ↳ id string required
      Unique identifier for this agent pool.
    • ↳ name string required
      Human-readable name for this agent pool.
    • ↳ description string required
      User-provided description of the agent pool’s purpose.
    • ↳ lastSeen integer required
      Unix epoch timestamp (seconds) when any agent in the pool last reported a heartbeat.
    • ↳ status enum required
      Aggregate status of agents in the pool (e.g. idle, busy, offline).
      Values: online, offline
    • ↳ lastDeployment integer optional
      Unix epoch timestamp (seconds) of the most recent deployment executed by this pool. Null if no deployments have run.
    • ↳ isDefault boolean required
      Whether this pool is the organization’s default workflow runner pool.
    • defaultAgentPoolID string optional
      The ID of the organization’s default agent pool. Omitted if the organization uses the Pulumi Hosted Pool.
    Errors: 403 Forbidden

    Create Org Agent Pool

    ▼
    POST /api/orgs/{orgName}/agent-pools

    Creates a new agent pool for an organization. Agent pools enable self-hosted deployment agents, allowing organizations to run Pulumi Deployments on their own infrastructure rather than Pulumi-managed infrastructure. This is useful for accessing private networks, meeting compliance requirements, or using custom execution environments. The response includes an access token (agent pool secret) that self-hosted agents use to authenticate when polling for deployment work. This token is only returned once at creation time and cannot be retrieved later.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: CreateOrgAgentPoolRequest
    • name string required
      The name
    • description string required
      The description

    Responses

    200 OK
    Schema: CreateAccessTokenResponse
    • id string required
      The unique identifier
    • tokenValue string required
      The token value
    Errors: 400 Metadata object store endpoint is not configured 403 Forbidden

    Get Agent Pool

    ▼
    GET /api/orgs/{orgName}/agent-pools/{poolId}

    Returns the details of a specific agent pool, including its name, ID, creation timestamp, and configuration. Agent pools enable self-hosted deployment agents that run Pulumi Deployments on organization-managed infrastructure. The pool ID can be referenced in stack deployment settings to route deployments to self-hosted agents instead of Pulumi-managed infrastructure.

    Request Parameters

    • orgName string path required
      The organization name
    • poolId string path required
      The agent pool identifier

    Responses

    200 OK
    Schema: AgentPoolDetail
    • created integer required
      The creation timestamp
    • id string required
      The unique identifier
    • name string required
      The name
    • description string required
      The description
    • agents array[DeploymentAgentMetadata] required
      The agents
    • ↳ version string required
      The version of the deployment agent.
    • ↳ platform string required
      The platform the agent is running on.
    • ↳ hostname string required
      The hostname of the machine running the agent.
    • ↳ ip string required
      The IP address of the agent.
    • ↳ pid string required
      The process ID of the agent.
    • ↳ lastSeen integer required
      The Unix timestamp when the agent was last seen.
    • ↳ status enum required
      The current status of the deployment agent.
      Values: online, offline
    Errors: 403 Forbidden 404 AgentPool

    Patch Org Agent Pool

    ▼
    PATCH /api/orgs/{orgName}/agent-pools/{poolId}

    Updates an existing agent pool’s configuration for an organization. This can be used to modify the pool’s name or other configurable properties. The request body uses the same format as CreateOrgAgentPool. Only provided fields are updated; omitted fields remain unchanged.

    Request Parameters

    • orgName string path required
      The organization name
    • poolId string path required
      The agent pool identifier

    Request Body

    Schema: CreateOrgAgentPoolRequest
    • name string required
      The name
    • description string required
      The description

    Responses

    200 OK
    Schema: PatchOrgAgentPoolResponse
    • name string required
      The updated name of the agent pool after the patch operation.
    • description string required
      The updated description of the agent pool after the patch operation.
    Errors: 403 Forbidden 404 AgentPool

    Delete Org Agent Pool

    ▼
    DELETE /api/orgs/{orgName}/agent-pools/{poolId}

    Deletes an agent pool from an organization. If the agent pool is currently referenced by any stack’s deployment settings, the deletion will fail with a 400 error unless the ‘force’ query parameter is set to true. Force-deleting a pool that is in use will cause affected stacks to fall back to Pulumi-managed infrastructure for future deployments. Returns 204 No Content on success.

    Request Parameters

    • orgName string path required
      The organization name
    • poolId string path required
      The agent pool identifier
    • force boolean query optional
      Force the operation even if the pool is in use

    Responses

    204 No Content
    Errors: 400 Agent pool is in use 403 Forbidden 404 AgentPool