Core Concepts

The mental model behind Syntropic137 — events, workspaces, workflows, and observability.

You don't need to understand event sourcing to use Syntropic137. This page gives you the mental model — the "why" behind what you see in the dashboard and CLI.

Two Kinds of Events

Syntropic137 separates all data into two lanes, each optimized for its purpose:

	Domain Events	Observability Events
Purpose	Source of truth for business logic and state transitions	High-throughput telemetry for dashboards and debugging
Storage	TimescaleDB (append-only, replay-safe)	TimescaleDB (hypertable, time-series optimized)
Pipeline	Command → Aggregate → Event → Projection	Agent stdout → Collector → EventBuffer → TimescaleDB
Examples	`WorkflowCreated`, `ExecutionCompleted`, `TriggerFired`	`ToolExecuted`, `TokensUsed`, `StreamChunk`

Domain events are the source of truth for what happened. The current state of any workflow or execution is derived by replaying its events — there's no mutable database row to corrupt.

Observability events are append-only telemetry. They power the dashboard metrics, cost tracking, and session timelines. They never affect business logic.

Workspaces

Every agent execution runs inside an isolated Docker container — a workspace. Workspaces use a two-phase security model:

Setup Phase — Secrets (API keys, Git credentials) are briefly available to configure credential helpers. Raw tokens are cleared before the agent starts.
Agent Phase — The agent runs with only ANTHROPIC_API_KEY in its environment. Git operations use cached credentials from the setup phase. Network egress goes through an Envoy sidecar proxy.

This means the agent never sees raw GitHub tokens or other secrets. Even if an agent is compromised, credentials are already gone.

Workflows

A workflow is a YAML definition of work to be done. It consists of one or more phases, where each phase is a task for an AI agent:

id: research-v1
name: Research Workflow
phases:
  - id: discovery
    prompt_file: phases/discovery.md
    model: sonnet
  - id: synthesis
    prompt_file: phases/synthesis.md
    model: opus

Phases execute sequentially. Each phase can reference the output of previous phases using {{phase-id}} substitution. The $ARGUMENTS variable passes user input into the prompt.

Workflows can be packaged and distributed — see Workflow Packages.

Executions

An execution is a running instance of a workflow. It progresses through a state machine:

NOT_STARTED→ start →RUNNING→ finish →COMPLETED

RUNNING→ error →FAILED

RUNNING→ pause →PAUSED→ resume →RUNNING

RUNNING→ interrupt →INTERRUPTED→ retry →RUNNING

PAUSED→ cancel →CANCELLED

You can pause, resume, and cancel executions in real time via the REST API or the CLI. The agent can only be paused at safe yield points — between phases, after tool calls, or after LLM responses.

Sessions

A session is an agent's working period within an execution. It captures:

Conversation — the full message history
Tool timeline — every tool call with input, output, and duration
Token metrics — input/output tokens per model
Cost — calculated from token usage and model pricing

Sessions are the primary unit of observability. When you debug a failed execution or analyze costs, you're looking at session data.

Artifacts

Artifacts are outputs produced by agents — code files, reports, design documents, test results. They're stored in MinIO (S3-compatible object storage) and linked to their source execution.

Triggers

A trigger connects a GitHub event to a workflow. When a matching event arrives (PR opened, push to main, issue labeled), the trigger automatically starts a workflow execution.

Triggers have built-in safety limits:

Guard	Purpose
`daily_limit`	Maximum executions per day
`cooldown`	Minimum seconds between executions
`budget`	Maximum spend before pausing

See GitHub Integration for setup details.