# Podomy / Concord Complete Documentation Context
# Generated for LLMs, AI agents, Cursor/Copilot, and context windows
# Repository: https://github.com/podomy/concord
# Website: https://podomy.com
# Manifest: https://podomy.com/llms.txt
# Exported: 2026-08-26T19:01:13.500Z

================================================================================
FILE: overview.md
URL: https://podomy.com/docs/overview.md
================================================================================

# Overview

Concord is a coordination layer for distributed systems with unreliable, intermittent, or partitioned connections.

Traditional distributed systems freeze or fail when machines lose network access because they depend on a central truth or synchronous quorums (like etcd/Raft). Concord is built from the ground up for environments where networks are degraded, intermittent, or absent. Every node operates independently from its local journal and synchronizes state deterministically whenever connections become available.

---

## Core Philosophy

1. **Local-first execution**: A node always trusts its local journal to execute workloads, even with zero peers reachable.
2. **Deterministic reconciliation**: State is an append-only event log. There is no central master or hidden database.
3. **Zero daemon bloat**: Direct OCI/runc container execution with cgroups isolation.
4. **Autonomous mesh**: Encrypted peer-to-peer WireGuard mesh with SWIM gossip discovery.

---

## Three Primitives

* **Journal**: An append-only log of immutable events (`workload.spec`, `workload.tombstone`, `node.started`).
* **Workloads**: Declarative specifications defining execution parameters, environment, ports, and health checks.
* **Mesh**: Automatic WireGuard tunnels connecting nodes with mutual TLS authentication.

---

## Next Steps

* [Architecture](architecture.md) -> How Concord works under the hood.
* [CLI Reference](cli.md) -> Command line commands and usage.
* [Go SDK](sdk.md) -> Programmatic workload management.
* [Deployment](deployment.md) -> Running nodes and clustering.


================================================================================
FILE: architecture.md
URL: https://podomy.com/docs/architecture.md
================================================================================

# Architecture & Data Flow

Concord is a decentralized coordination engine. State is driven by an append-only event log, projected into local views, reconciled against container runtimes, and synchronized across nodes over an encrypted mesh.

---

## Data Flow Diagrams

### 1. Workload Submission Flow

```
CLI / Go SDK
     │
     │ (1) POST /workload/submit
     │     (JSON Workload Spec)
     ▼
Unix IPC Server
(~/.config/concord/concord.sock)
     │
     │ (2) Record "workload.spec"
     │     Event
     ▼
Append-Only Journal
(journal.jsonl)
     │
     │ (3) Deterministic
     │     Projection
     ▼
bbolt KV Views
(Workloads, EventsByID, ByNode)
```

### 2. Local Workload Reconciliation & Execution Flow

```
bbolt KV Views (Desired State)
     │
     │ (4) Active Workload Specs
     ▼
Reconciler Loop
     │
     ├──► (5) Fetch Image
     │         │
     │         ▼
     │    Embedded OCI Registry
     │    (Zot localhost:8444)
     │
     └──► (6) Lifecycle Control
               │
               ▼
          Container Runtime
          (internal/cr)
               │
               ├──► cgroups (CPU/Mem)
               │
               ├──► runc (Namespaces)
               │
               ├──► Bridge & veth (concord0)
               │
               └──► Health Checker (/health)
```

### 3. Peer Discovery & WireGuard Mesh Flow

```
Node Discovery
     │
     ├──► mDNS (LAN Multicast)
     │         │
     ├──► SWIM Gossip (UDP :17946)
     │         │
     └──► DNS Server (SRV/A :15353)
               │
               ▼
     Peer Memberlist
               │
               │ (7) Exchange WG Keys & IPs
               ▼
     WireGuard Mesh (internal/cn)
     (Flat Encrypted P2P Overlay)
```

### 4. Cross-Node State & Image Replication Flow

```
[ Remote Node B ]
Transport Server & Registry
       │
       │ (8) mTLS Pull Events
       │ (10) P2P Image/Blob Sync
       │ (Over WireGuard Mesh)
       ▼
[ Local Node A ]
Peer Sync Loop (internal/peersync)
       │
       ├──► (9) Missing Events
       │         │
       │         ▼
       │    Local Journal (journal.jsonl)
       │         │
       │         ▼
       │    Local bbolt Views
       │         │
       │         ▼
       │    Reconciler ──► runc
       │
       └──► (10) Missing Blobs
                 │
                 ▼
            Embedded OCI Registry
            (localhost:8444)
```

---

## Scheduling

In each connected segment, the node with the lowest UUID string is the leader. It assigns unassigned workloads to the peer with the fewest active workloads. When segments reunite, journals sync and state converges.


================================================================================
FILE: cli.md
URL: https://podomy.com/docs/cli.md
================================================================================

# CLI Reference

Concord uses a noun-first command structure: `concord <noun> <action> [flags]`.

---

## Starting the Daemon

```bash
# Start the node daemon in the foreground
concord
# or explicitly:
concord daemon
```

---

## Workload Commands

### Run a Workload
```bash
concord workload run [flags] <image> [command...]
```

**Flags:**
| Flag | Short | Default | Description |
| :--- | :--- | :--- | :--- |
| `--port` | `-p` | `""` | Port mapping: `host:container` (e.g. `8080:80`) |
| `--env` | `-e` | `[]` | Environment variables in `KEY=VAL` format (repeatable) |
| `--restart` | | `always` | Policy: `always`, `never`, `on_failure` |
| `--cpu` | | `1024` | CFS CPU shares (`1024` = 1 core) |
| `--memory` | | `0` | Memory limit in MB (`0` = unlimited) |
| `--health-path` | | `/health` | HTTP endpoint for health checks |
| `--health-action` | | `restart` | Action on failure: `restart` or `signal` |

**Examples:**
```bash
# Run nginx with port mapping
concord workload run -p 8080:80 nginx:alpine

# Run with environment variables and memory limit
concord workload run -e ENV=prod -e DB_HOST=10.0.0.5 --memory 512 redis:alpine

# Run with custom entrypoint command
concord workload run alpine:latest /bin/sh -c "while true; do echo hello; sleep 5; done"
```

---

### List Workloads
```bash
concord workload list
```

**Output:**
```
ID          IMAGE              PORTS       RESTART   HEALTH
4b8d7a12    nginx:alpine       8080:80     always    /health
9c1e3f80    redis:alpine       -           always    -
```

---

### Inspect a Workload
```bash
# Supports full UUIDs or 8-character prefixes
concord workload inspect 4b8d7a12
```

Returns the full JSON specification for the workload.

---

### Stop a Workload
```bash
# Stops container and writes a tombstone event to the journal
concord workload stop 4b8d7a12
```

---

## Node Commands

### List Cluster Nodes
```bash
concord node list
```

**Output:**
```
NODE ID                                ADDRESS             STATE    WIREGUARD PUBLIC KEY
a1b2c3d4-e5f6-7890-abcd-ef1234567890   192.168.1.10:17946  alive    +abc123xyz...
```

---

## Autocompletion

```bash
# Bash
source <(concord completion bash)

# Zsh
source <(concord completion zsh)

# Fish
concord completion fish | source
```


================================================================================
FILE: sdk.md
URL: https://podomy.com/docs/sdk.md
================================================================================

# Go SDK Reference

```bash
go get github.com/podomy/concord/sdk
```

`sdk.Dial()` connects to `~/.config/concord/concord.sock`.

```go
client, err := sdk.Dial()
if err != nil {
    log.Fatalf("connect to concord daemon: %v", err)
}
defer client.Close()
```

## Example

```go
spec, err := sdk.NewWorkload().
    Image("docker.io/library/nginx:alpine").
    Port(8080, 80).
    Env("ENV", "production").
    Restart(sdk.RestartAlways).
    CPUShares(1024).
    MemoryMB(512).
    HealthCheck("/healthz", sdk.HealthActionRestart).
    Build()
if err != nil {
    log.Fatalf("invalid spec: %v", err)
}

id, err := client.Submit(context.Background(), spec)
if err != nil {
    log.Fatalf("submit workload: %v", err)
}
fmt.Printf("Workload submitted: %s\n", id)
```

## API

| Method | Description |
| :--- | :--- |
| `client.Submit(ctx, w)` | Submit a workload, returns its UUID |
| `client.Stop(ctx, id)` | Stop and remove a workload |
| `client.Get(ctx, id)` | Fetch a workload spec by UUID |
| `client.List(ctx)` | List active workloads |
| `client.Nodes(ctx)` | List cluster nodes |

Builder methods: `Image`, `Command`, `Env`, `Envs`, `Port`, `Resources`, `MemoryMB`, `CPUShares`, `Restart`, `HealthCheck`, `StopTimeout`, `StopTimeoutSeconds`, `Build`, `MustBuild`.


================================================================================
FILE: deployment.md
URL: https://podomy.com/docs/deployment.md
================================================================================

# Deployment Guide

Concord runs on Linux edge nodes, servers, and embedded controllers.

---

## Prerequisites

- **Operating System**: Linux kernel 5.10+ (cgroups v2, network namespaces).
- **Architecture**: `amd64`, `arm64`, `armv7`, or `riscv64`.
- **Runtime**: Root or `CAP_SYS_ADMIN` privileges (required by `runc` for container namespacing).

---

## Installation

### 1. Download Pre-compiled Binary

```bash
# Example for Linux amd64:
curl -LO https://github.com/podomy/concord/releases/download/v1.0/concord-linux-amd64.zip
unzip concord-linux-amd64.zip
chmod +x concord-linux-amd64
sudo mv concord-linux-amd64 /usr/local/bin/concord
rm concord-linux-amd64.zip
```

### 2. Build from Source

```bash
go install github.com/podomy/concord@latest
```

---

## Running Concord as a Systemd Service

Create `/etc/systemd/system/concord.service`:

```ini
[Unit]
Description=Concord Fleet Node
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/concord daemon
Restart=always
RestartSec=3
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
```

Enable and start the service:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now concord
```

Check status:

```bash
systemctl status concord
```

## Cluster Trust & Certificate Authority (CA) Provisioning

All nodes in a Concord cluster authenticate each other via mutual TLS (mTLS). **Every single node in the cluster must be provisioned with the exact same Root Certificate Authority (`ca.crt` and `ca.key`).**

Before starting any Concord node for the first time, upload your cluster's shared CA files to its config directory (defaults to `~/.config/concord/certs`):

```bash
# Must be executed on EVERY node in the cluster:
mkdir -p ~/.config/concord/certs
cp /path/to/shared/ca.crt ~/.config/concord/certs/ca.crt
cp /path/to/shared/ca.key ~/.config/concord/certs/ca.key
chmod 600 ~/.config/concord/certs/ca.key
```

> **Custom Config Directory**: Concord adheres to the XDG Base Directory specification. You can override the base configuration directory by setting the `XDG_CONFIG_HOME` environment variable (e.g. `export XDG_CONFIG_HOME=/etc` will store certificates in `/etc/concord/certs`).

When Concord starts:
1. It verifies that the shared `ca.crt` and `ca.key` exist.
2. It automatically generates a unique node identity (`UUID`) and mints a local `node.crt` and `node.key` signed by the shared CA.
3. If pre-minted `node.crt` and `node.key` already exist alongside `ca.crt`, it reuses them directly.

Because every node is signed by the same Root CA, all nodes can mutually verify each other's identity across the mesh.

---

## Multi-Node Cluster Discovery

Concord nodes automatically discover each other over the local subnet using SWIM gossip (UDP port `17946`).

When a node starts:
1. It initializes its mutual TLS identity from `~/.config/concord/certs/`.
2. It listens for gossip announcements from peer nodes on the local network.
3. Once discovered, nodes establish an encrypted WireGuard mesh and sync journal events over mTLS.

No central master server, control plane, or external database is required.