Polycrate API for Teams: Centralized Monitoring and Remote Triggering

TL;DR

• The Polycrate API transforms individual workspaces into a team platform: all workspaces, action runs, and SSH sessions are centrally visible—ideal for operations, compliance, and audits.
• Remote triggering via the API replaces local CLI installations in CI/CD pipelines and on jump hosts: build agents communicate with Polycrate via HTTP, and the rest runs in standardized containers.
• Workspace validation and centralized encryption key management become reusable services for your entire team; platform HTTP endpoint monitoring runs through the API and Polycrate Operator (not via a block in workspace.poly).
• The Polycrate API web dashboard provides team leads and compliance officers with a clear overview: who triggered what, when, and where—including reporting functions.
• ayedo offers an enterprise feature with the Polycrate API that seamlessly integrates into your platform engineering initiatives—including support from our consulting.

Polycrate API as a Team Platform Instead of Individual CLI

With plain Ansible, automation often looks like this:

• Each person has their own local installation (often with different Python versions).
• Playbooks are distributed across Git repos, script folders, and home directories.
• CI/CD pipelines reinstall Ansible per build agent or use custom-built images.
• Audits become manual log collection projects.

Ansible is an excellent automation tool—but it doesn’t inherently provide a central platform for teams. This is where Polycrate comes in: Ansible always runs in a container with a defined toolchain, and the Polycrate API turns it into an enterprise platform.

The Polycrate API offers you:

• Central view of all your team’s workspaces
• History of all action runs (including exit status, logs, artifacts)
• Overview of all SSH sessions established via Polycrate
• Uniform, auditable interface for external systems (e.g., CI/CD)

More technical details can be found in the API documentation.

Architecture: Workspaces, Blocks, and API Interaction

Polycrate structures automation through workspaces and blocks. The API understands this structure and makes it usable for teams.

A typical workspace might look like this:

# workspace.poly
name: acme-corp-automation
organization: acme

blocks:
  - name: linux-patch
    from: linux-patch
    config:
      target_hosts: "all"

  - name: windows-patching
    from: cargo.ayedo.cloud/ayedo/infra/windows-patching:0.4.2
    config:
      maintenance_window: "Sun 02:00-04:00"

The API knows:

• Which blocks are instantiated in which workspace.
• Which block versions are used (always pinned, never :latest).
• What configuration is set per block.

A block you develop locally might look like this:

# blocks/linux-patch/block.poly
name: linux-patch
version: 0.1.0
kind: generic

config:
  target_hosts: "all"

actions:
  - name: patch
    description: "Security patches on Linux servers"
    playbook: patch.yml

The corresponding inventory is located—as prescribed by Polycrate—in the workspace root:

# inventory.yml
all:
  hosts:
    server01.acme-corp.com:
      ansible_user: ubuntu
    server02.acme-corp.com:
      ansible_user: ubuntu

Important: Polycrate executes all playbooks in a container. This eliminates the classic dependency problem (different Ansible or Python versions, missing tools) and creates reproducible results—whether you work locally or the Polycrate API triggers.

Remote Triggering: CI/CD Without Local Polycrate Installation

In many teams, CI/CD integration with plain Ansible looks like this today:

# Build agent (e.g., GitLab Runner)
pip install ansible==9.4.0
ansible-playbook -i inventory.yml deploy.yml

Or you build your own Docker images with Ansible and tooling, which you have to maintain in all pipelines. Both create maintenance overhead and supply chain risks.

With Polycrate, a centrally operated Polycrate API endpoint is sufficient. Your pipeline only needs to make an HTTP call, and the actual polycrate run takes place on the platform:

# Example: Run action locally (for comparison only)
polycrate run linux-patch patch

In the CI/CD pipeline, your job instead calls the API, for example:

curl -X POST \
  -H "Authorization: Bearer $POLYCRATE_TOKEN" \
  -H "Content-Type: application/json" \
  https://polycrate.example.com/api/v1/workspaces/acme-corp-automation/actions \
  -d '{
    "block": "linux-patch",
    "action": "patch",
    "reason": "Nightly patch run from CI",
    "parameters": {
      "extra_vars": {
        "patch_profile": "security-only"
      }
    }
  }'

This is a simplified illustration: the exact path, authentication, and request body follow your API version and your instance’s OpenAPI specification.

The API:

• Validates whether the workspace exists.
• Checks if the block linux-patch and the action patch are defined.
• Starts the run in a standardized container.
• Returns a run ID, which you can use later to retrieve status and logs.

Unlike a directly executed ansible-playbook in the pipeline, you benefit from:

• Uniform toolchain in the container (kubectl, Helm, Python, etc.)—no individual setup anymore.
• Central audit log: Every pipeline action appears in the Polycrate API (web UI).
• Sharable automation: The same block design can be shared and reused by other workspaces or teams via registry.

Workspace Validation: Registered Blocks and Compatible Versions

When multiple teams use the same block—e.g., an official ayedo block from the PolyHub—you want to ensure that:

• Only approved block versions are used.
• Workspaces don’t accidentally revert to old, insecure versions.
• New versions are rolled out in a controlled manner.

The Polycrate API can validate workspaces:

• Are all from: references directed to known registries and block names?
• Are the used versions approved in your company?
• Do API compatibility and configuration match the defined block schema?

This validation can also be triggered remotely—as a quality gate in a GitOps pipeline, for example, before a merge into the main branch occurs. Details on best practices for blocks and versioning can be found in the Polycrate Best Practices.

This makes the Polycrate API a technical enforcer of your architectural and compliance requirements, without each team having to maintain their own validation scripts.

Integrated HTTP endpoint monitoring (not via workspace.poly)

The endpoint monitoring bundled with the Polycrate API (reachability of URLs/hosts via HTTP and ICMP, agents, evaluation in the API) is a separate subsystem: it uses Endpoint resources in the API and monitoring agents—not an Ansible block in workspace.poly like the ones you use with polycrate run. In Kubernetes environments, the Polycrate Operator plays a central role (including endpoint discovery from Ingress and synchronization with the API). Details: Polycrate Operator and API documentation.

Independently, you can still trigger any action remotely—for example the linux-patch block above for maintenance runs. That is the same pattern as in the “Architecture” and “Remote Triggering” sections; it does not replace the platform’s integrated endpoint monitoring.

Centralized Encryption Key Management for Team Workspaces

Polycrate comes with built-in workspace encryption using age. Sensitive files—such as artifacts/secrets/kubeconfig.yml or SSH keys—can thus be securely versioned in the Git repo. Details can be found in the documentation on workspace encryption.

Without the Polycrate API, this often means in practice:

• Manually distributing age keys via chat, email, password manager.
• Uncertainty about who has which keys.
• Tedious rotation when team members join or leave.

The Polycrate API complements this with:

• A central key store per organization.
• Access control: Which users or service accounts are allowed to decrypt which workspaces?
• Integration with the CLI: The CLI can retrieve the corresponding keys via the API when opening an encrypted workspace—no more manual copy & paste.

You initialize encryption with the CLI, for example:

# Encrypt workspace (simplified)
polycrate workspace encrypt

The key comes from the configured Polycrate API (recommended) or from the WORKSPACE_ENCRYPTION_KEY environment variable—see Workspace encryption and API integration – Workspace Encryption Key Management. polycrate workspace encrypt has no recipient flags (no --age-recipient); the CLI encrypts secrets.poly and artifacts/secrets/** using the provided age key.

When you use the API, it handles management of which keys belong to which workspaces, who may use them, and how rotation is organized. For compliance teams, this is a central component: key management becomes traceable, documented, and audit-proof.

Dashboard and Reporting: What Team Leads See in the Polycrate API

The Polycrate web interface based on the API is the view into the heart of your automation platform. Typical views for team leads and compliance officers:

• Workspaces Overview
  List of all registered workspaces, including metadata (owner, last activity, number of blocks, encryption status).

• Action Runs
  Temporal representation of all runs—filterable by workspace, block, action, status, or triggering system (e.g., “GitLab CI”, “ServiceNow”, “manual via CLI”). From each entry, you can open logs and relevant artifacts.

• SSH Sessions
  Transparency over all SSH connections established via Polycrate—including user, target host, time, and optional purpose tag. For many compliance requirements (e.g., ISO 27001, SOC 2), this is a significant step forward.

• Compliance View
  Overview of which workspaces are validated, where outdated block versions are used, or which workspaces are not encrypted. This makes the Polycrate API a practical compliance backbone.

In many platform engineering initiatives, this transparency is exactly what’s needed: automation should scale without governance falling by the wayside. The Polycrate API provides the necessary data and interfaces for this—and ayedo can support you with our consulting to embed this data effectively in your processes.

Polycrate API as a Compliance Backbone

Regulatory requirements such as the GDPR (binding in the EU since 25.05.2018) or industry-specific standards demand traceable processes:

• Who triggered which infrastructure change and when?
• Where does sensitive configuration data live—and is it encrypted?
• How do you ensure only approved automation building blocks are used?

With the Polycrate API you consolidate:

• All action runs (including context: workspace, block, action, trigger).
• All SSH sessions.
• Encryption status and key assignment for workspaces.
• The version of every block used in production.

Instead of scattered log files, different Ansible versions, and ad-hoc evaluation scripts, you have a single, documented API as the basis for reports, dashboards, and audits. For enterprise architects and compliance officers, that is the shift from “automation somehow works” to “automation is a clear, controlled process.”

More technical details on the Polycrate API can be found in the official API documentation.

Frequently Asked Questions

Do I need the Polycrate API to use Polycrate?

No. Polycrate works without the API purely via the CLI—including container execution, workspaces, blocks, workspace encryption, and registry integration. The Polycrate API comes into play when you want to:

• Centralize across teams or the whole organization,
• Connect CI/CD pipelines without a local CLI installation,
• Or need unified monitoring, reporting, and compliance.

In short: individual users or small teams can rely on the CLI alone. For enterprise scenarios, the API shines.

How does Polycrate differ from a home-grown Ansible runner service?

Many companies build internal “Ansible runners” with a small REST API, a few Docker containers, and a database. That can work, but it means:

• You write and maintain the code yourself.
• You define how workspaces, inventories, credentials, and logs are managed.
• You carry responsibility for security and updates.

Polycrate ships these aspects as a product:

• Standardized model (workspaces, blocks, actions, workflows).
• Containerized execution with a defined toolchain.
• Registry integration for shareable automation.
• Built-in workspace encryption and centralized key management.
• API and web UI aligned with this structure.

You do not need to invent your own orchestrator—you can rely on a documented, proven platform.

What role does ayedo play in operating and integrating the Polycrate API?

ayedo develops and operates Polycrate and supports you:

• With architecture and rollout of the platform in existing environments.
• With integration into your CI/CD landscape and compliance processes.
• With developing your own blocks and using the PolyHub ecosystem.

Whether you want a dedicated enterprise deployment or to integrate Polycrate into an existing platform—we bring experience from many projects and tailor solutions to your environment.

More questions? See our FAQ

From Theory to Practice

With the Polycrate API, a strong automation tool becomes a central platform for teams and organizations: workspaces, blocks, and actions are no longer driven only locally via the CLI, but are available as well-defined services—including remote triggering, monitoring, workspace validation, and encryption key management.

In this article you have seen how:

• Polycrate bundles all execution in standardized containers, solving plain Ansible’s classic dependency problem.
• The API serves as a uniform interface for CI/CD pipelines, monitoring jobs, or self-service portals—without a local Polycrate installation.
• Central capabilities such as workspace validation, key management, and—with Kubernetes—endpoint monitoring via API and Polycrate Operator support your compliance requirements and simplify audits.

For many organizations, the Polycrate API fits neatly into existing platform engineering initiatives: you get a reusable foundation for automation that Linux and Windows admins, IoT teams, and compliance officers can use alike. If you want help with architecture, integration, or block design, ayedo is available through our consulting.

If you want to evaluate the Polycrate API as an enterprise feature in your environment, start with a focused use case—for example replacing local ansible-playbook invocations in a CI/CD pipeline with remote triggering via the API. That is where the benefits of standardization, traceability, and centralized monitoring show up fastest.

Good next steps:

• Polycrate API documentation
• Workshops