Core Concepts

Two Kinds of Events

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

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:

1. Setup Phase: Secrets (API keys, Git credentials) are briefly available to configure credential helpers. Raw tokens are cleared before the agent starts.
2. Agent Phase: A claude phase runs with its Anthropic credential, ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN, as its only runtime secret. Other non-secret variables such as session and endpoint configuration are also present. A codex phase runs with an empty agent environment: its credential is staged to ~/.codex/auth.json at mode 0600 during provisioning and the staged copy is deleted, so CODEX_AUTH_JSON itself never reaches the agent. That asymmetry is deliberate, and it is what keeps Anthropic credentials out of reach of a codex run. 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
repos:
  - https://github.com/acme/api-service
  - https://github.com/acme/web-app
phases:
  - id: discovery
    name: Discovery
    order: 1
    prompt_file: phases/discovery.md
    agent:
      provider: claude
      model: sonnet
  - id: synthesis
    name: Synthesis
    order: 2
    prompt_file: phases/synthesis.md
    agent:
      provider: codex
      model: gpt-sol

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.

The repos list tells Syntropic137 which repositories to pre-clone into the workspace before the agent starts. See Workspace Hydration.

Workflows can be packaged and distributed. See Workflow Packages.

Agent Harnesses

Syntropic137 is not tied to a single agent vendor. Each phase declares which harness runs it, in the phase's agent block:

• provider: claude runs the phase on Claude Code (claude -p). This is the default when no agent block is present.
• provider: codex runs the phase on OpenAI Codex (codex exec).

Both harnesses use the same workspace image, the same isolation model, the same token accounting, and the same tool-call timeline. They differ in what they can enforce and what telemetry they emit. Claude phases produce hook events, subagent tracking, and todo data. Codex phases produce none of those.

See Choosing an Agent Harness for the full field reference and the caveats.

Executions

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

You can cancel a running execution or inject context into it in real time via the REST API or the CLI. The agent only acts on a signal at safe yield points: between phases, after tool calls, or after LLM responses.

A run that ended without finishing can be resumed: that creates a new execution which inherits the phases that completed and restarts at the first one that did not. See Resuming Failed Executions.

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.

A run can hold more sessions than its phases: delegates an agent starts inside its workspace, and the native transcripts each harness records. Finding every session in a workflow run explains how to list all of them, with lineage, coverage and gaps.

Codex sessions are thinner than claude sessions. Tokens and the tool timeline are captured for both, but codex does not report its model on the wire, so the platform prices a codex phase from the model it asked codex to run: the phase's model, or the gpt-sol default (priced as gpt-6-sol). Vendor cost is always null for codex.

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:

See GitHub Integration for setup details.