{ "pages": [ { "url": "/docs/", "title": "Archie", "section": "", "body": "# Archie\n\n**Event-driven Agentic Automation**\n\nArchie connects events from your systems to agents that can investigate, reason,\nand act. Define what an event means, map its data into a workflow, and give that\nworkflow an agent equipped for the job: its own execution environment, tools,\nand identity.\n\nThe aim is to automate work across system administration, incident response,\nnetwork operations, service management, and software delivery. You define the\nprocess and the access it requires; agents work through its stages, using the\ncontext of each event to decide how to accomplish the task.\n\nArchie is under active development. The model below describes the project's\napproved direction, with implementation progressing across event automation and\norganisation access control. The\n[event automation design](/dev/prds/event-automation/) and\n[organisations and access design](/dev/prds/orgs-and-access/) describe those\ncapabilities and their delivery stages.\n\n## From an event to an outcome\n\n```text\nEvent source → Event type → Mapping → Binding → Workflow → Agent\n```\n\n| Concept | Purpose |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **Source** | Receive events from a system such as a firewall, monitoring stack, service desk, or forge. Configure its endpoint and signing requirements. |\n| **Event type** | Identify which kind of event arrived from its headers and payload. Infer a schema from captured events or a pasted example. |\n| **Mapping** | Extract named, typed parameters from the event. Reuse a mapping across bindings and see how often it matches. |\n| **Binding** | Select a workflow, filter the events that should trigger it, and supply its inputs from mapped values or constants. |\n| **Workflow** | Define the stages of work, their inputs and outputs, and the agent profile to use. Call other workflows when work needs another specialist or process. |\n| **Agent** | Execute the work in a container with the tools for its purpose, acting under its own identity and granted permissions. |\n\nA single source can produce several event types. An event type can feed several\nbindings, and each binding can apply its own conditions. This lets the same\nincoming data drive different responses without building a custom integration\nfor every workflow.\n\nFor example, a firewall sends a blocked-connection event. Archie identifies the\nevent type and maps the source address and severity into an investigation\nworkflow. A network investigator gathers evidence, assesses the activity, and\nreturns its findings. The workflow could then call a separate containment\nworkflow, subject to the permissions and approvals configured for that action.\n\nThe same model supports other processes:\n\n- **Infrastructure operations:** A monitoring alert starts a diagnostic workflow\n to inspect a service, collect evidence, and propose or perform an authorised\n recovery action.\n- **Service management:** An incoming request supplies the parameters for a\n triage, investigation, or fulfilment workflow.\n- **Software delivery:** A forge event starts a review or implementation\n workflow with the repository's toolchain, validation steps, and pull request\n as its output.\n\nThese are examples of workflows you can build. Their behaviour comes from the\nworkflow, tools, and access you configure.\n\n## Agents equipped for their work\n\nAn agent profile selects the container image and available tools. You can supply\nimages with the software needed for a particular environment: network utilities\nfor an investigator, operational tooling for a systems agent, or a language\nruntime and test framework for repository work.\n\nWorkflows declare structured inputs and can return structured outputs. They can\nrun with a scratch workspace, require a repository, or accept one optionally. An\ninvestigation can finish with a report; a maintenance workflow can finish with\nan operational result; a coding workflow can finish with a pull request.\n\nWorkflows can also call other workflows and pass data between them. Each called\nworkflow has its own run and agent profile. A caller can wait for the result or\ncontinue while the called workflow runs independently.\n\nSee the\n[firewall investigation example](https://github.com/samcharles93/archie-core/blob/main/examples/workflows/firewall-investigate.yaml)\nfor a workflow that uses typed inputs, a network investigator profile, and no\nrepository.\n\n## Organisations, identities, and controlled execution\n\nThe approved access model organises automation into **organisations** and\n**workspaces**. An organisation owns its members, agent identities, secrets,\nprofiles, and workflows. Workspaces group sources, mappings, bindings, and runs\nby team responsibility or environment, such as network operations in production.\nEach organisation can enable the default workflows it needs and add its own.\n\nAgents act as their own identities. A workflow names the identity it runs as;\nsecrets and permissions are granted to that identity. Starting an agent is an\naudited action, with a record of the workflow and the event or member that\ninitiated it.\n\nThe design combines roles for routine administration with attribute-based\npolicies for resources and execution context. Policies apply from the instance\nthrough the organisation, workspace, identity, workflow, and individual object.\nLower levels can narrow access, and a denial takes precedence. Organisation and\nworkspace policy also determines which actions require approval from another\nmember.\n\nAuthorised runs receive credentials scoped to their identity, workspace, and\nwork. Event data supplies the task's inputs; it cannot grant additional access.\nThe [organisations and access design](/dev/prds/orgs-and-access/) defines this\nmodel; it remains an active implementation area.\n\n## Building and operating automations\n\nThe dashboard brings together event inspection, mappings, bindings, workflows,\nand task activity. The intended authoring path starts with a real payload or an\nexample: identify its structure, map the fields you need, select a workflow, and\napprove the binding.\n\nSources default to signed delivery. The event automation design also allows an\nexplicitly approved unsigned source for systems that cannot sign payloads, with\nthat status visible to operators. Binding changes require re-approval before\nthey can dispatch work.\n\nPlaybooks and extension points provide additional orchestration through\nworkflows, modules, channels, and forges. The\n[playbook engine design](/dev/prds/eda-playbook-engine/) describes how\nregistered capabilities become actions that event rules can call.\n\n## Start here\n\n- [First playbook](/docs/guides/first-playbook/) — connect an event source to a workflow.\n- [Deployment examples](https://github.com/samcharles93/archie-core/blob/main/deployments/README.md) — configure and run Archie.\n- [Architecture](/dev/architecture/) — domain boundaries and settled design.\n- [Development guides](/dev/development/) — contribute to Archie.\n" }, { "url": "/docs/guides/first-playbook/", "title": "Building your first playbook binding", "section": "Guides", "body": "# Building your first playbook binding\n\nThis walks through the whole no-code path the event-capture epic promises:\npoint an external app's webhook at archie, see the real payload it sends,\nmap the fields you care about, bind them to a workflow, and watch the next\nmatching event turn into a task -- no code, no redeploy, no restart. See\n`docs/architecture/bindings.md` for the model and threat model behind each\nstep below.\n\n## 1. Send a test event\n\nPoint whatever external app you want archie to react to at:\n\n```\nPOST http://\u003cyour-archied-host\u003e:8484/webhooks/capture/\u003csource\u003e\n```\n\n`\u003csource\u003e` is a name you choose for this sender (e.g. `sentry`, `github-ci`,\n`stripe`) -- it's just a URL path segment, not a preset list. Send one real\nevent however is easiest for a first test, e.g.:\n\n```bash\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -d '{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\n```\n\nThis event isn't signed yet, so it's captured but marked **unauthenticated**\n-- visible for you to design against, but incapable of triggering anything\n(`docs/architecture/bindings.md`'s threat-model section explains why: an\nunauthenticated event can never match a binding, no matter how it looks).\n\n## 2. Inspect the captured payload\n\nOpen the dashboard's **Event inspector** (`/captures`). Your test event\nappears there with its real body -- this is schema-by-example: you're\nlooking at an actual payload from the actual sender, not guessing at a\nschema in advance.\n\n## 3. Map the fields you care about\n\nOpen **Field mappings** (`/mappings`) → **New mapping**. Pick your captured\nevent from the dropdown, then click through its payload tree on the right --\nevery key and value is clickable. Clicking a value binds it as a field\n(name, JSON path, and an inferred type you can change). Add whichever fields\nyour workflow needs (e.g. the issue title), mark the ones that must be\npresent as **Required**, hit **Preview** to confirm they resolve correctly\nagainst the real payload, then **Save**.\n\n## 4. Create the binding\n\nOpen **Playbook bindings** (`/bindings`) → **New binding**:\n\n- **Name** -- anything descriptive.\n- **Source** -- the same `\u003csource\u003e` segment from step 1 (e.g. `sentry`).\n- **Field mapping** -- the one you just saved.\n- **Workflow** -- which registered workflow should run on a match.\n- **Repo pin** (optional) -- leave both blank to use the single configured\n repo; set owner/repo explicitly if you run a multi-repo deployment.\n- **Shared secret** -- a real secret (16+ bytes), never `test1234`. The\n sender signs every request body with this via HMAC-SHA256 so archie can\n tell a genuine event from anyone who finds the URL.\n\nSave. The binding starts in **draft** -- nothing fires yet.\n\n## 5. Approve it\n\nA **draft** or freshly-**edited** binding needs an explicit human approval\nbefore it can ever match a live event -- this is deliberate, not a missing\nstep: an operator authoring a binding is a considered act, an event arriving\nis not, and nothing should self-arm (`docs/architecture/bindings.md`'s\nthreat-model section, point 2). Click **Approve**. Status becomes **armed**.\n\n## 6. Fire it for real\n\nSend the same kind of event again, this time **signed** with the binding's\nsecret:\n\n```bash\nBODY='{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\nSECRET=\"the-secret-you-set-in-step-4\"\nSIG=$(printf '%s' \"$BODY\" | openssl dgst -sha256 -hmac \"$SECRET\" | sed 's/^.* //')\n\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Hub-Signature-256: sha256=$SIG\" \\\n -d \"$BODY\"\n```\n\nThis event is captured as **authenticated**, matched against your armed\nbinding, and dispatched into a new task through the exact same\ngate/worktree/sandbox pipeline every other task goes through -- see\n`docs/architecture/messaging-and-work-intake.md`'s \"Intake provenance\". Check\nthe **Tasks** page; a new task should appear, its body built from the fields\nyour mapping resolved.\n\n## Editing a live binding\n\nAny edit to an armed binding -- even a typo fix -- drops it back to\n**pending_approval** automatically. This can't be bypassed by editing; it\nhas to be re-approved. When editing, leave the **Shared secret** field blank\nto keep the existing secret; only fill it in if you're deliberately\nrotating it.\n" } ], "nav": [ { "title": "Archie", "url": "/docs/" }, { "title": "Guides", "items": [ { "title": "Building your first playbook binding", "url": "/docs/guides/first-playbook/" } ] } ] }