Config Reference

Root object

A Seristack configuration is a YAML document containing a stacks list.

stacks:
- name: system-health
  count: 1
  cmds:
  - echo "system-health is good"

Stack attributes

Each item under stacks represents an executable Seristack stack.

Variables

Variables are declared with the vars list. They can be referenced by stack commands through the Seristack variable template syntax.

vars:
- name: env
  value: staging
  required: true
  allowed_value:
  - staging
  - production

Example

vars:


- name: environment
  value: staging
  required: true
  allowed_value:
  - staging
  - production

- name: version
  required: true
  allowed_regex: regex("^[a-zA-Z0-9._-]+$")

- name: command
  denied_regex: regex("(?i)rm|delete|drop")

Dependencies

A stack can depend on one or more other stacks using dependsOn.

stacks:
- name: build
  cmds:
  - ./build.sh

- name: test
  dependsOn:
  - build
  cmds:
  - ./test.sh

- name: deploy
  dependsOn:
  - test
  cmds:
  - ./deploy.sh

Seristack resolves the dependency graph before execution. Dependencies allow larger workflows to be composed from smaller stacks.

Execution modes

Timeouts

The timeouts field controls the maximum duration allowed for command execution.

timeouts: 30s

Go duration units include ns, us, µs, ms, s, m, and h.

Shell settings

Seristack can execute commands using its supported shell execution mechanisms. The shell and shellArg fields allow an external shell to be selected where supported.

Example: Bash

shell: bash


shellArg: -c

Example: PowerShell

shell: powershell


shellArg: -Command

Commands, output, and registry

cmds

The cmds field contains the commands executed by the stack.

cmds:
- |
  echo "starting"
  ./script.sh
  echo "finished"

output

The output field can be used to process accumulated stack output.

output: |

echo '{{.Self.result}}' |
grep "^{" |
jq -s '{records: ., total: length}'

discardOutput

Use discardOutput to remove selected output/result entries from the registry after execution.

discardOutput:

- build
- test

HTTP behavior

A stack can be associated with an HTTP endpoint using method and urlPath.

stacks:

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

  - ./deploy.sh

Request variables

HTTP requests can provide declared variables through supported request inputs such as query parameters, request bodies, and headers.

# Query parameter

curl "http://127.0.0.1:8080/deploy?env=staging"

# JSON body

curl -X POST http://127.0.0.1:8080/deploy 
-H "Content-Type: application/json" 
-d '{"env":"staging","version":"v1.2.3"}'

Per-stack authorization HTTP

A stack can define access rules based on identity headers supplied by a trusted authentication proxy.

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

  cmds:

  - ./deploy.sh

access

matchAccess

Examples

# Group-based access

access:

- headerName: X-Auth-Request-Groups
  headerValue:

  - sre
  - platform

# Group AND role must match

matchAccess: ALL

access:

- headerName: X-Auth-Request-Groups
  headerValue:

  - devops

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

  - admin

# Specific user

access:

- headerName: X-Auth-Request-Email
  headerValue:

  - [oncall@company.com](mailto:oncall@company.com)

Audit logging

Structured JSON audit logging can be enabled from the command line.

seristack run \


--config config.yaml 
--audit-log /var/log/seristack/audit.log

Audit entries can contain information such as:

• Timestamp
• Event type
• Stack name
• HTTP path and method
• Source IP when available
• Identity information
• Variables
• Success or failure
• Execution duration
• Output and error information

{


"timestamp": "2026-09-19T10:00:00Z",
"event": "stack_executed",
"stack": "system-health",
"path": "/health",
"method": "GET",
"success": true,
"duration_ms": 42,
"output": "system-health is good"
}

Querying logs

# Failed executions


jq 'select(.success == false)' 
/var/log/seristack/audit.log

# Slow executions

jq 'select(.duration_ms > 30000)' 
/var/log/seristack/audit.log

# Executions for a specific stack

jq 'select(.stack == "system-health")' 
/var/log/seristack/audit.log

MCP behavior

Seristack can expose configured stacks through the Model Context Protocol (MCP).

seristack mcp \


-t streamableHTTP 
--addr 127.0.0.1 
--port 8081

Stacks with a description can be registered as MCP tools. Declared variables can be provided as tool arguments.

Recommended deployment

MCP client / IDE
   │
   ▼
 HTTPS
   │
   ▼


nginx / authentication proxy
│
├── TLS
├── Authentication
└── Identity propagation
│
▼
Seristack MCP
127.0.0.1:8081
│
▼
Stack execution

Security considerations

Seristack executes shell commands on the machine where it runs. Treat the configuration as executable operational code.

• Bind Seristack to localhost or a private network when possible.
• Put an authenticated reverse proxy or gateway in front of remotely accessible HTTP and MCP endpoints.
• Use HTTPS/TLS for remote access.
• Do not trust identity headers directly from public clients.
• Apply per-stack authorization to sensitive workflows.
• Run the process with the minimum operating-system privileges required.
• Avoid putting credentials or secrets in YAML variables.
• Review shell commands before exposing them through HTTP or MCP.
• Protect and rotate audit logs.

Testing

Run the complete Go test suite with:

go test ./...

To force all tests to execute instead of using Go's test cache:

go test -count=1 ./...

For verbose output and individual test execution times:

go test -count=1 -v ./...

Run tests for a specific package:

go test -count=1 -v ./pkg/opsy

Run the race detector:

CGO_ENABLED=1 go test -race ./...

Complete example

stacks:


- name: build
  description: Build the application

  count: 1
  executionMode: SEQUENTIAL
  timeouts: 10m

  cmds:

  - ./build.sh

- name: test
  description: Run application tests

  dependsOn:

  - build

  count: 1
  executionMode: SEQUENTIAL
  timeouts: 10m

  cmds:

  - ./test.sh

- name: deploy-production
  description: Deploy the application to production

  method: POST
  urlPath: /deploy/production

  dependsOn:

  - test

  matchAccess: ALL

  access:

  - headerName: X-Auth-Request-Groups
    headerValue:

    - platform
    - sre

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

    - admin

  count: 1
  executionMode: SEQUENTIAL
  timeouts: 10m

  vars:

  - name: version
    required: true
    allowed_regex: regex("^[a-zA-Z0-9._-]+$")

  - name: environment
    value: production
    required: true
    allowed_value:

    - staging
    - production

  cmds:

  - |
    echo "Deploying {{.Vars.version}}"
    echo "Environment: {{.Vars.environment}}"
    ./deploy.sh "{{.Vars.version}}" "{{.Vars.environment}}"

  output: |
  echo '{{.Self.result}}'

- name: cleanup
  description: Cleanup temporary resources

  dependsOn:

  - deploy-production

  count: 1
  executionMode: SEQUENTIAL
  timeouts: 30s

  cmds:

  - ./cleanup.sh

  discardOutput:

  - deploy-production

Start the HTTP server

seristack run \

--config config.yaml 
--addr 127.0.0.1 
--port 8080 
--audit-log /var/log/seristack/audit.log

Start the MCP server

seristack mcp \


-t streamableHTTP 
--addr 127.0.0.1 
--port 8081