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_seconds (a timed-out mutating step is not retried unless it opts in), for_each fan-out, and run_when failure/cleanup edges
• Safety first — plan by default; real changes require explicit opt-in. For GCP create and IAM tools a plan reads the live resource and reports unchanged / create / update / recreate_required
• 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 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/sarala-ai/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
    required: true

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

A step that times out is killed and fails. Because the cloud operation behind a killed CLI call may still be running, a mutating tool is not retried after a timeout unless the step sets retry.retry_on_timeout: true.

Preview, plan, then apply:

# Print the steps, tools and parameters (reads no cloud state)
apex plan workflows/gcp/publish-python-package.yml

# Plan against live GCP (default mode, writes nothing; needs credentials)
apex run workflow run --workflow workflows/gcp/publish-python-package.yml \
  --params '{"project_id":"my-project","repo_name":"my-packages","location":"us-central1"}'

# Apply against real GCP (opt-in)
apex run workflow run --workflow workflows/gcp/publish-python-package.yml \
  --params '{"project_id":"my-project","repo_name":"my-packages","location":"us-central1"}' \
  --execution-mode apply

The apex CLI is the primary interface. Key commands:

apex --version   # Print the installed apex-core version
apex init        # Initialize an APEX-aware project from a natural-language brief
apex plan        # Print the steps of a workflow without running it
apex run workflow run  # Plan (default) or apply (--execution-mode apply) a workflow
apex run         # Execute resource-server tools directly
apex docs        # Browse the guidance and guides that ship with the package
apex workflows   # List and show the workflow catalog
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

The full command tree is in docs/guidance/reference/cli.md.

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 mode. No real infrastructure is created or changed without an explicit --execution-mode apply (or equivalent opt-in).

A plan is not an offline simulation for GCP. Create and IAM tools (clusters, node pools, projects, service accounts, IAM bindings, custom roles, billing links, API enablement) read the live resource and report the action apply would take: unchanged, create, update, add, remove, or recreate_required. Planning them needs read access, a read that fails fails the plan, and a step APEX cannot see ends unverified and exits 1. Other tools return a preview without contacting the cloud. See plan semantics and read-first tools.

Scope honesty: APEX does not run a continuous drift-detection or reconciliation loop (read-first GCP tools compare live state to a step at plan and apply time, nothing more), 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/

• Unit tests run on every pull request
• The GCP integration suite runs in CI against a scratch GCP project
• Coverage is enforced in CI

Documentation

• APEX White Paper
• Documentation Map
• CLI reference
• Self-hosting guide
• Workflow DSL
• 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: see apex --version and the CHANGELOG
• Python: 3.10+
• 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.