seristack

# Seristack

[![Go Reference](https://pkg.go.dev/badge/github.com/TechXploreLabs/seristack.svg)](https://pkg.go.dev/github.com/TechXploreLabs/seristack)
[![Go Version](https://img.shields.io/badge/go-1.26.6-00ADD8?logo=go)](https://go.dev/)
[![License](https://img.shields.io/github/license/TechXploreLabs/seristack)](LICENSE)
[![Release](https://img.shields.io/github/v/release/TechXploreLabs/seristack?include_prereleases)](https://github.com/TechXploreLabs/seristack/releases)

**One YAML configuration. CLI commands, HTTP endpoints, and MCP tools.**

Seristack is a lightweight automation engine for DevOps, Platform, SRE, and Cloud teams.

Define shell-based workflows in YAML, manage dependencies and variables, execute them locally or through HTTP, and expose selected stacks as MCP tools for AI agents and IDE integrations.

[GitHub Repository](https://github.com/TechXploreLabs/seristack)

## Why Seristack?

Operational workflows often live as shell scripts, runbooks, CI jobs, and undocumented procedures.

Seristack provides a single configuration layer for turning those workflows into reusable execution stacks that can be:

* Run from the CLI
* Exposed as HTTP endpoints
* Exposed as MCP tools
* Protected with per-stack authorization
* Audited with structured JSON logs
* Composed using dependencies and shared results

## Documentation

* [Configuration Reference](docs/config-reference.md)

## Features

* 🚀 Run multiple command stacks from a single YAML configuration
* 🔁 Execute stacks sequentially or concurrently
* 🔢 Repeat stack execution with configurable counts
* 🔗 Define dependencies between stacks
* 🧩 Variable substitution with validation rules
* 📦 Share output and results between dependent stacks
* 🌐 Expose stacks as HTTP endpoints
* 🔐 Per-stack authorization using identity headers
* 📋 Structured JSON audit logging
* 🧠 Run as an MCP server for AI agents and IDE integrations
* 🛠 Support for mvdan shell, Bash, sh, and PowerShell
* ⏱ Per-stack execution timeouts
* 📁 Configurable working directories
* 🛡 Allow and deny rules for stack variables

---

## Installation

### Homebrew — macOS and Linux

```bash
brew install TechXploreLabs/tap/seristack
```

### Linux — installer

```bash
curl -fsSL https://raw.githubusercontent.com/TechXploreLabs/seristack/main/install.sh | bash
```

### Linux — release archive

1. Go to [Seristack Releases](https://github.com/TechXploreLabs/seristack/releases).
2. Download the latest:

```text
seristack_VERSION_linux_ARCH.tar.gz
```

For example:

```text
seristack_0.4.1_linux_amd64.tar.gz
```

3. Extract the archive:

```bash
tar -xzf seristack_VERSION_linux_ARCH.tar.gz
```

4. Install the binary:

```bash
sudo mv seristack /usr/local/bin/
sudo chmod +x /usr/local/bin/seristack
```

5. Verify:

```bash
seristack --help
```

### Windows — installer

Run PowerShell as a user with permission to install the binary:

```powershell
irm https://raw.githubusercontent.com/TechXploreLabs/seristack/main/install.ps1 | iex
```

### Windows — release archive

1. Go to [Seristack Releases](https://github.com/TechXploreLabs/seristack/releases).
2. Download the Windows release archive:

```text
seristack_VERSION_windows_ARCH.tar.gz
```

For example:

```text
seristack_0.4.1_windows_amd64.tar.gz
```

3. Extract the archive with a tool that supports `.tar.gz`.

4. Place `seristack.exe` in a directory included in your `%PATH%`.

5. Verify:

```powershell
seristack --help
```

---

## Configuration

Seristack uses YAML to define execution stacks.

For a complete description of all configuration fields, see the [Configuration Reference](docs/config-reference.md).

### Example

```yaml
stacks:

  - name: stack1
    workDir: ./
    description: Print welcome message
    method: GET
    urlPath: /show
    continueOnError: false
    count: 3
    timeouts: 1h
    executionMode: PARALLEL

    vars:
      - name: samplekey
        value: samplevalue
        required: true
        allowed_value:
          - samplevalue
          - devvalue

    cmds:
      - |
        export samplekey={{.Vars.samplekey}}
        echo $samplekey
        echo "count={{.Count.index}}"
        echo "Hey I'm Seristack!"

  - name: stack2
    workDir: ./
    continueOnError: false
    count: 3
    executionMode: SEQUENTIAL

    vars:
      - name: env
        value: Dev

    dependsOn:
      - stack1

    cmds:
      - |
        echo "{\"index\": {{.Count.index}}, \"step\": \"metadata\", \"status\": \"ok\"}"

      - |
        echo "{\"index\": {{.Count.index}}, \"step\": \"metrics\", \"value\": $((RANDOM % 100))}"

    output: |
      echo "--- Aggregation Summary ---"
      echo '{{.Self.result}}' | grep "^{" | jq -s '{
        total_records: length,
        environment: "{{.Vars.env}}",
        results: .
      }'
```

---

## Running stacks

### Trigger all stacks

```bash
seristack trigger -c config.yaml
```

### Trigger a specific stack

```bash
seristack trigger -c config.yaml -s stack1
```

### Start the HTTP server

```bash
seristack run -c config.yaml
```

### Start the MCP server

```bash
seristack mcp -t streamableHTTP
```

---

## HTTP server

The HTTP server exposes configured stacks as HTTP endpoints.

For example:

```yaml
stacks:
  - name: system-health
    method: GET
    urlPath: /health
    cmds:
      - echo "system-health is good"
```

Start the server:

```bash
seristack run \
  --config config.yaml \
  --addr 127.0.0.1 \
  --port 8080
```

A reverse proxy such as nginx or Caddy can expose the service externally while Seristack remains bound to localhost.

---

## Production deployment

Seristack executes shell commands and should **not be exposed directly to the public internet**.

A recommended architecture is:

```text
Client
  │
  ▼
nginx / Caddy
  │
  ├── TLS termination
  ├── Authentication
  ├── Rate limiting
  │
  ▼
Seristack
127.0.0.1
  │
  ├── Authorization
  └── Command execution
```

Start Seristack on localhost:

```bash
seristack run \
  --config config.yaml \
  --addr 127.0.0.1 \
  --port 8080
```

For a remote MCP deployment, the same pattern can be used:

```text
AI Agent / IDE
      │
      ▼
    HTTPS
      │
      ▼
nginx / oauth2-proxy
      │
      ├── TLS
      ├── OIDC authentication
      └── Identity headers
      │
      ▼
Seristack MCP
127.0.0.1:8081
      │
      ├── Stack authorization
      └── Command execution
```

Authentication should be handled by the identity-aware proxy or gateway, while Seristack performs authorization at the individual stack level.

---

## Per-stack authorization

Seristack can restrict individual stacks using identity headers forwarded by an authenticated reverse proxy.

For example:

```yaml
stacks:

  - name: deploy-production
    method: POST
    urlPath: /deploy/production

    matchAccess: ANY

    access:
      - headerName: X-Auth-Request-Groups
        headerValue:
          - sre
          - platform

      - headerName: X-Auth-Request-Roles
        headerValue:
          - admin

    count: 1

    cmds:
      - ./deploy.sh
```

### Access matching

`matchAccess` controls how multiple access rules are evaluated.

#### ANY

```yaml
matchAccess: ANY
```

Access is granted when **at least one** access rule matches.

This is OR logic.

#### ALL

```yaml
matchAccess: ALL
```

Access is granted only when **every** access rule matches.

This is AND logic.

#### No access rules

If a stack does not define an `access` block, there is no stack-level access restriction.

The authentication layer should still protect the service itself in production.

### Identity headers

The actual headers depend on the authentication provider and reverse proxy.

| Identity provider   | Common proxy         | Example identity information                                            |
| ------------------- | -------------------- | ----------------------------------------------------------------------- |
| Entra ID / Azure AD | oauth2-proxy         | `X-Auth-Request-Groups`, `X-Auth-Request-Roles`, `X-Auth-Request-Email` |
| GCP                 | IAP                  | `X-Goog-Authenticated-User-Email`                                       |
| AWS Cognito         | ALB                  | `X-Amzn-Oidc-Data`                                                      |
| OCI IAM             | nginx + oauth2-proxy | `X-Auth-Request-Groups`, `X-Auth-Request-Email`                         |
| Okta / Auth0        | oauth2-proxy         | Identity headers configured by the proxy                                |

The headers must be configured and trusted only when they originate from your authenticated proxy.

Do not allow untrusted external clients to directly supply authorization headers.

---

## Audit logging

Seristack can write a structured JSON audit log for stack executions.

Enable audit logging:

```bash
seristack run \
  --config config.yaml \
  --audit-log /var/log/seristack/audit.log
```

Audit entries include information such as:

* Timestamp
* Event
* Stack name
* HTTP path and method
* Source IP when available
* Identity headers
* Variables
* Success/failure
* Execution duration
* Output
* Error information

Example:

```json
{
  "timestamp": "2026-09-19T10:00:00Z",
  "event": "stack_executed",
  "stack": "system-health",
  "success": true,
  "duration_ms": 42,
  "output": "system-health is good"
}
```

Use `logrotate` or an equivalent logging system to manage log rotation.

### Do not put secrets in stack variables

Variables may be included in audit records.

Avoid passing passwords, tokens, API keys, or other secrets as stack variables.

Prefer:

* Environment variables
* Secret managers
* Workload identity
* External credential providers

---

## MCP server

Seristack can expose configured stacks as MCP tools.

Start a Streamable HTTP MCP server:

```bash
seristack mcp \
  -t streamableHTTP \
  --addr 127.0.0.1 \
  --port 8081
```

Stacks with a `description` can be exposed as MCP tools.

AI agents and MCP-compatible IDEs can then discover and invoke the a