APEX Platform

Multi-Cloud Infrastructure Orchestration with YAML Workflows

APEX is a local-first CLI and MCP tool for orchestrating cloud infrastructure with declarative YAML workflows, state interpolation, and execution planning. Built safety-first: plan / dry-run mode by default, no accidental infrastructure changes.

APEX is complementary to Terraform, not a replacement — some workflows even wrap the terraform CLI.

Key Features

• YAML workflows — declarative, list-based steps: with state interpolation (${step.output})
• DSL control flow — step-level retry + timeout, for_each fan-out, and run_when failure/cleanup edges
• Safety first — plan / dry-run by default; real changes require explicit opt-in
• Opt-in remote state — local SQLite by default, with optional GCS-backed run-record sync (apex state sync)
• MCP-native — exposes tools over the Model Context Protocol (FastMCP) for IDE / agent callers
• Agent mode — --output json for machine-readable, non-TTY output
• DevTools workflows — CI dispatch/watch/triage and a dogfooded release pipeline

Provider Support

GCP is the primary, most-built provider. Its 15 resource servers cover: artifact_registry, bigquery, cloud_run, cloud_sql, firebase, iam, identity_platform, inventory, networking, org_policy, project, pubsub, redis, secret_manager, and storage. The tests/integration/gcp/ suite runs green (29/29) in CI against a scratch GCP project.

DevTools resource servers ship alongside the cloud providers: test_runner, code_quality, health_check, validation, ci_runs (GitHub Actions dispatch/watch/triage), and release_ops (release preflight + git tag/push).

Quick Start

Installation

# Using uv (recommended)
uv pip install apex-core[gcp]

# Using pip
pip install apex-core[gcp]

# For development
git clone https://github.com/apex-core/apex-core
cd apex-core
uv sync --group dev --extra gcp

Run a workflow

Workflows use a list-based steps: format. Each step names a resource server (server_type), a tool_name, and parameters. Outputs from earlier steps are referenced with ${...} interpolation.

name: publish_python_package
version: "1.0"
description: "Build and publish a Python package to GCP Artifact Registry"

inputs:
  project_id:
    type: string
    required: true
  repo_name:
    type: string
    required: true
  location:
    type: string
    default: "asia-south1"

entry_point: ensure_repo

steps:
  - name: ensure_repo
    server_type: gcp_artifact_registry
    tool_name: create_repository
    parameters:
      project_id: "${project_id}"
      repository: "${repo_name}"
      location: "${location}"
      format: "python"
    # Bootstrap steps can retry through eventual-consistency lags:
    retry:
      max_attempts: 3
      delay_seconds: 5
      backoff_multiplier: 2
    timeout_seconds: 120

Preview the plan, then execute:

# Preview the execution plan (no changes)
apex plan --workflow workflows/gcp/publish-python-package.yml

# Execute against real GCP (opt-in)
apex workflow run publish-python-package.yml \
  --params '{"project_id":"my-project","repo_name":"my-packages","location":"asia-south1"}' \
  --execute

The apex CLI is the primary interface. Key commands:

apex init        # Initialize an APEX-aware project from a natural-language brief
apex plan        # Preview an execution plan without running it
apex workflow run  # Execute a workflow
apex run         # Execute resource-server tools directly
apex state       # Manage run-record state (sync / list / pull)
apex validate    # Validate resource-server configs and workflow DSL
apex mcp         # Start the MCP server for IDE integration

AWS workflows run the same way (server_type: aws_vpc, aws_ecs, …) using boto3-backed servers.

DSL Control Flow

Step-level retry and timeout (spec 018) — retry eventual-consistency-prone steps and bound their runtime:

- name: enable_apis
  server_type: gcp_project
  tool_name: enable_apis
  retry: { max_attempts: 3, delay_seconds: 5, backoff_multiplier: 2 }
  timeout_seconds: 300

for_each fan-out (spec 019) — iterate a step over a dynamic input list instead of hand-numbered resource_1..resource_N:

- name: create_buckets
  server_type: gcp_storage
  tool_name: create_bucket
  for_each: "${bucket_names}"
  parameters:
    name: "${item}"

run_when failure-condition edges (spec 020) — declarative error / cleanup branching:

- name: rollback_notice
  server_type: health_check
  tool_name: notify
  run_when: { step: deploy, condition: failed }

State Management

State is local-first (SQLite) by default. apex state sync opts a project into a GCS-backed run-record backend (git-like: push local records to a bucket, read them back elsewhere). This is opt-in per project via .apex/settings.yaml:

state_sync:
  backend: gcs
  bucket: gs://my-apex-state
  prefix: apex

apex state sync            # push instance records / plan specs / audit logs to the bucket
apex state list --source remote   # list run records in the remote bucket
apex state pull            # read remote records back locally

This is a local-first store with an optional remote — not a distributed state store or a server.

Safety Features

All operations default to plan / dry-run mode. No real infrastructure is created or changed without an explicit --execute (or equivalent opt-in). Dry-run generates realistic mock results so workflows can be validated end-to-end without cloud cost.

Scope honesty: APEX does not do drift detection/reconciliation, and executed rollback against a real cloud is not proven (LIFO rollback ordering exists in the DSL model only). It is not a Terraform replacement, and it is not a multi-tenant / SaaS / web service — it is a local-first CLI + MCP tool.

Testing

# Unit tests
pytest tests/unit/

# GCP integration suite (requires a scratch GCP project + credentials)
pytest tests/integration/gcp/

• 2782 unit tests passing (13 skipped)
• GCP integration suite green (29/29) against a real scratch GCP project in CI
• Coverage is enforced in CI

Documentation

• APEX White Paper
• Documentation Map
• Tech Plan 2026
• v0.4.0 Plan
• Contributing Resource Servers
• Contributing

Contributing

Contributions welcome — see CONTRIBUTING.md and docs/CONTRIBUTING_RESOURCE_SERVERS.md for how to add resource servers, testing requirements, and the PR process.

Project Status

• Version: 0.4.0
• Python: 3.9+
• Status: Active development — GCP-first, local-first CLI + MCP tool

v0.4.0 is the first release shipped via APEX's own dogfooded apex-release workflow (APEX releasing APEX to GCP Artifact Registry).

License

PolyForm Small Business License 1.0.0 — see LICENSE for details.

Free for individuals and for organizations with fewer than 100 people and under $1M USD annual revenue. Larger organizations need a commercial license — contact the maintainers.

Acknowledgments

Built with:

• FastMCP — Model Context Protocol integration
• Pydantic — data validation
• boto3 — AWS SDK

Note: APEX runs in plan / dry-run mode by default. Real infrastructure changes require explicit opt-in and correctly configured cloud credentials.