API Integration

Polycrate's HTTP API integration with the PolyHub: configuration, ActionRun and CLI activity submission, template block publishing, maintenance window pre-flight, kubeconfig and encryption key management, the endpoint monitoring agent and CLI instance tracking.

API Integration

Polycrate supports integration with the PolyHub via an HTTP API. This integration makes it possible to submit action results, synchronize workspace data and use further cloud features.

API configuration

The API integration is configured globally in the Polycrate configuration file ($HOME/.polycrate/polycrate.yml) or via CLI flags/environment variables – not in the workspace.

Global configuration file (recommended)

Create or edit ~/.polycrate/polycrate.yml:

# ~/.polycrate/polycrate.yml
api:
  enabled: true
  url: https://hub.polycrate.io
  api_key: <your-api-key>
  submit_action_runs: true          # ActionRuns + CLI activities (SSH, sync, …)
  submit_template_blocks: true      # template to the API after blocks push
  validate_workspace_on_load: false

# Pre-flight (global, not under api:)
check_maintenance_window: true
sync_loopback_kubeconfig: true

CLI flags

# Enable the API
polycrate run my-block install --api-enabled

# Set the API URL
polycrate run my-block install --api-url https://hub.polycrate.io

# API key for authentication
polycrate run my-block install --api-api-key <your-api-key>

# Submit action results
polycrate run my-block install --api-submit-action-runs

Environment variables

export POLYCRATE_API_ENABLED=true
export POLYCRATE_API_URL=https://hub.polycrate.io
export POLYCRATE_API_API_KEY=<your-api-key>
export POLYCRATE_API_SUBMIT_ACTION_RUNS=true

Showing the configuration

# Show the current API configuration and status
polycrate api

API features

Workspace clone

polycrate workspace clone ORG/WORKSPACE [PATH] fetches an existing API workspace locally: lookup by name and organization, clone from git_ssh_url via go-git. Without API config, without access rights or without a Git URL the command fails.

polycrate workspace clone acme/acme-production-1

Default target: $HOME/.polycrate/workspaces/<ORG>/<WORKSPACE>. The optional PATH is the parent directory.

→ CLI reference: workspace clone · Workspaces

ActionRun submission

When --api-submit-action-runs is enabled (default), the results of every action execution are automatically submitted to the API.

# Default: enabled
polycrate run my-block install

# Disable explicitly
polycrate --no-api-submit-action-runs run my-block install

Submitted data:

Features:

• Fail-safe design: API errors never block successful actions
• Retry logic: automatic retries with exponential backoff
• Offline-tolerant: with network problems the action still runs through

Use cases:

• Central monitoring of all action executions in the team
• History and audit trail for compliance
• Error analysis and reporting
• Deployment tracking across all workspaces

CLI activity submission (audit)

In addition to ActionRuns, CLI activities are submitted to the API — provided the API is active and submit_action_runs is not disabled:

Submitted metadata (examples): cli_version, execution_host, user, os, arch; SSH: hostname, block, ssh_user.

Purpose: audit trail (compliance). API errors do not block the operation (fail-safe).

Template blocks after blocks push (since 0.51.0)

After a successful OCI push the CLI publishes the block metadata as a template block to the API (api.submit_template_blocks, default: true). Prerequisite: API credentials + api.enabled.

polycrate blocks push my-block
# Disable: --api-submit-template-blocks=false

Errors during publish (e.g. HTTP 409) abort the push (hard). Details → CLI reference — blocks push.

Maintenance window (pre-flight)

Before interactive action runs the CLI checks whether the workspace is within an API-side maintenance window (check_maintenance_window, default: true). Outside the window a confirmation appears; declining aborts the run. In CI / non-interactive mode the check is skipped.

polycrate run my-block install --check-maintenance-window=false

Kubeconfig from the API

All clusters: polycrate k8s sync-kubeconfigs → Kubernetes — Kubeconfig synchronization.

Before an interactive run the CLI can reconcile the workspace-local kubeconfig with the API credential (sync_loopback_kubeconfig, historical name). Not when falling back to ~/.kube/config.

Logs & metrics via the API

With API access, terminal queries against VictoriaLogs / VictoriaMetrics are available:

polycrate logs --query '_msg:error' --start 1h
polycrate metrics 'up'

→ Observability — Logs & metrics · CLI reference

Workspace encryption key management

The API centrally manages the encryption keys for encrypted workspaces. This is the recommended solution for teams.

How it works:

1. Automatic key retrieval: the CLI automatically fetches the workspace encryption key from the API
2. Highest priority: API keys override local environment variables
3. Workspace-specific: every workspace receives its own encryption key
4. Team sharing: all team members with API access can decrypt the workspace

Credential types:

The API stores encryption keys as workspace credentials with the following properties:

• Kind: workspace-encryption
• Private key (ssh_private_key): age secret key for encryption/decryption
• Public key (ssh_public_key): age public key (derived automatically)
• State: READY, PENDING or ERROR

Example workflow:

# 1. Configure the API
cat > ~/.polycrate/polycrate.yml << EOF
api:
  enabled: true
  url: https://hub.polycrate.io
  api_key: your-api-key
EOF

# 2. Encrypt the workspace (key is fetched from the API)
polycrate workspace encrypt

# 3. Team member clones the repository
git clone <repo>
cd workspace

# 4. Decrypt the workspace (key is fetched automatically from the API)
polycrate workspace decrypt

Advantages:

• ✅ No manual key sharing required
• ✅ Central key rotation possible
• ✅ Audit logging of all key accesses
• ✅ Automatic state tracking

For details see Workspace encryption.

Workspace validation

With --api-validate-workspace-on-load the workspace is validated against the API when loaded:

polycrate run my-block install --api-validate-workspace-on-load

This checks:

• Whether all blocks are registered in the API
• Whether the versions used are compatible
• Whether security updates are available

Showing API information

polycrate api

Shows the current API configuration and connection status.

PolyHub integration

The PolyHub at hub.polycrate.io is the official API implementation of Polycrate.

Authentication

You can authenticate with username/password or API key:

# With API key
polycrate hub inspect ayedo/k8s/cluster --hub-api-key <your-key>

# With username/password
polycrate hub inspect ayedo/k8s/cluster --hub-username user --hub-password pass

Hub commands

# Fetch block information from the Hub
polycrate hub inspect <block-name>

Example:

polycrate hub inspect ayedo/k8s/cluster
# Shows: description, available versions, actions, dependencies, etc.

Environment variables

For sensitive data such as API keys, using environment variables is recommended:

export POLYCRATE_API_KEY="your-api-key"
export POLYCRATE_API_URL="https://hub.polycrate.io"

polycrate run my-block install --api-enabled

Security

• API keys should never be stored in the workspace configuration
• Use environment variables or secure secret management solutions
• For encrypted workspaces, API keys can be stored in the encrypted configuration

API endpoint monitoring agent

The Polycrate monitoring agent continuously monitors HTTP and ICMP endpoints and reports results to the API.

Starting the agent

polycrate api agent \
  --agent-token "your-agent-token" \
  --max-concurrent-checks 10

Options:

Features

Flow

graph LR
    Agent[Polycrate Agent] -->|1. Fetch endpoints| API[Polycrate API]
    Agent -->|2. Run checks| Endpoints[HTTP/ICMP Endpoints]
    Endpoints -->|3. Results| Agent
    Agent -->|4. Send results| API

1. The agent fetches the endpoints to check from the API
2. Runs the configured checks (HTTP, ICMP)
3. Collects results (status, latency, errors)
4. Submits results to the API

Use cases

• Uptime monitoring: monitoring of production services
• Multi-region checks: agents in different regions
• Alerting: the API can alert on outages
• SLA tracking: capturing availability data

Example: systemd service

# /etc/systemd/system/polycrate-agent.service
[Unit]
Description=Polycrate Monitoring Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/polycrate api agent --agent-token "$TOKEN"
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable polycrate-agent
sudo systemctl start polycrate-agent

CLI instance tracking

Polycrate automatically tracks all CLI installations per user. With every ActionRun submission, information about the CLI installation is captured and synchronized with the API.

How it works

With every ActionRun the following data is submitted automatically:

Unique identification

Every CLI installation is uniquely identified by the combination:

(user, hostname, os, arch)

If you use the CLI on several machines or in different VMs/containers, each is tracked as a separate installation.

Version tracking

The system automatically detects CLI updates:

• current_version: the CLI version currently in use
• last_version: the previously used version (before the update)
• first_seen: when the installation was first registered
• last_seen: when the installation was last active

User interface

The CLI installations can be viewed in the Polycrate web UI:

Path: Account → Settings → CLI Installations

The overview shows:

• All registered CLI installations
• Current and previous versions
• Last activity per installation
• Number of ActionRun submissions

Privacy

• CLI installations are only visible to the respective user
• Administrators can view all installations for support purposes
• Data can be deleted on request (GDPR)

Disabling

CLI instance tracking is coupled to ActionRun submissions. If you disable ActionRun submissions, no CLI installation data is submitted either:

polycrate --no-api-submit-action-runs run my-block install

CLI reference

For a complete overview of all CLI commands see:

• CLI reference - Complete documentation of all commands
• PolyHub - More about the PolyHub
• Configuration - Workspace configuration