Also fix repository-free message.send validation (#2046) and add a single-binary development smoke path (#1977). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
168 lines
8.0 KiB
Markdown
168 lines
8.0 KiB
Markdown
<h1>
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="assets/brand/archie-wordmark-dark.svg">
|
|
<img alt="Archie" src="assets/brand/archie-wordmark.svg" height="56">
|
|
</picture>
|
|
</h1>
|
|
|
|
**Event-driven Agentic Automation**
|
|
|
|
Archie connects events from your systems to agents that can investigate, reason,
|
|
and act. Define what an event means, map its data into a workflow, and give that
|
|
workflow an agent equipped for the job: its own execution environment, tools,
|
|
and identity.
|
|
|
|
The aim is to automate work across system administration, incident response,
|
|
network operations, service management, and software delivery. You define the
|
|
process and the access it requires; agents work through its stages, using the
|
|
context of each event to decide how to accomplish the task.
|
|
|
|
Archie is under active development and not every capability below is
|
|
finished.
|
|
|
|
## From an event to an outcome
|
|
|
|
```text
|
|
Event source → Event type → Mapping → Binding → Workflow → Agent
|
|
```
|
|
|
|
| Concept | Purpose |
|
|
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| **Source** | Receive events from a system such as a firewall, monitoring stack, service desk, or forge. Configure its endpoint and signing requirements. |
|
|
| **Event type** | Identify which kind of event arrived from its headers and payload. Infer a schema from captured events or a pasted example. |
|
|
| **Mapping** | Extract named, typed parameters from the event. Reuse a mapping across bindings and see how often it matches. |
|
|
| **Binding** | Select a workflow, filter the events that should trigger it, and supply its inputs from mapped values or constants. |
|
|
| **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. |
|
|
| **Agent** | Execute the work in a container with the tools for its purpose, acting under its own identity and granted permissions. |
|
|
|
|
A single source can produce several event types. An event type can feed several
|
|
bindings, and each binding can apply its own conditions. This lets the same
|
|
incoming data drive different responses without building a custom integration
|
|
for every workflow.
|
|
|
|
For example, a firewall sends a blocked-connection event. Archie identifies the
|
|
event type and maps the source address and severity into an investigation
|
|
workflow. A network investigator gathers evidence, assesses the activity, and
|
|
returns its findings. The workflow could then call a separate containment
|
|
workflow, subject to the permissions and approvals configured for that action.
|
|
|
|
The same model supports other processes:
|
|
|
|
- **Infrastructure operations:** A monitoring alert starts a diagnostic workflow
|
|
to inspect a service, collect evidence, and propose or perform an authorised
|
|
recovery action.
|
|
- **Service management:** An incoming request supplies the parameters for a
|
|
triage, investigation, or fulfilment workflow.
|
|
- **Software delivery:** A forge event starts a review or implementation
|
|
workflow with the repository's toolchain, validation steps, and pull request
|
|
as its output.
|
|
|
|
These are examples of workflows you can build. Their behaviour comes from the
|
|
workflow, tools, and access you configure.
|
|
|
|
## Agents equipped for their work
|
|
|
|
An agent profile selects the container image and available tools. You can supply
|
|
images with the software needed for a particular environment: network utilities
|
|
for an investigator, operational tooling for a systems agent, or a language
|
|
runtime and test framework for repository work.
|
|
|
|
Workflows declare structured inputs and can return structured outputs. They can
|
|
run with a scratch workspace, require a repository, or accept one optionally. An
|
|
investigation can finish with a report; a maintenance workflow can finish with
|
|
an operational result; a coding workflow can finish with a pull request.
|
|
|
|
Workflows can also call other workflows and pass data between them. Each called
|
|
workflow has its own run and agent profile. A caller can wait for the result or
|
|
continue while the called workflow runs independently.
|
|
|
|
The archipelago marketplace's `workflows/firewall` package is an example of a
|
|
workflow that uses typed inputs, a network investigator profile, and no
|
|
repository.
|
|
|
|
## Identities and controlled execution
|
|
|
|
Agents act as their own identities, with secrets and permissions granted to
|
|
that identity. Runs receive credentials scoped to their task; event data
|
|
supplies inputs and cannot grant access. Organisations, workspaces and
|
|
policy-based access control are in progress.
|
|
|
|
## Building and operating automations
|
|
|
|
The dashboard brings together event inspection, mappings, bindings, workflows,
|
|
and task activity. The intended authoring path starts with a real payload or an
|
|
example: identify its structure, map the fields you need, select a workflow, and
|
|
approve the binding.
|
|
|
|
Sources default to signed delivery; an unsigned source must be explicitly
|
|
approved. Binding changes require re-approval before they can dispatch work.
|
|
|
|
## Run it on a server
|
|
|
|
You need x86_64 Linux with curl and unzip, Docker (agents and the bundled
|
|
PostgreSQL run in containers) and a model: local [Ollama](https://ollama.com)
|
|
or a hosted provider API key.
|
|
|
|
1. **Install.**
|
|
|
|
```bash
|
|
curl -fsSL https://offloaded.dev/install.sh | bash
|
|
```
|
|
|
|
It downloads the latest release, verifies its checksum, installs the five
|
|
services into `~/.local/bin` and runs `archied setup`. Setup asks for the
|
|
PostgreSQL URL (leave it blank for a bundled database with a generated
|
|
password), a model provider and key, and a forge (choose **none** for
|
|
event-driven automation only). Answers go to `~/.config/archie/config.toml`
|
|
and secrets to `~/.config/archie/env`. The installer then starts the
|
|
bundled PostgreSQL with Docker Compose and installs and starts systemd user
|
|
units. Pass options with `| bash -s -- --help`; `--from-source` builds a
|
|
checkout instead. Re-run `archied setup` at any time to change the answers.
|
|
|
|
Extensions run in an unprivileged user namespace. Ubuntu 23.10 and later
|
|
block these by default; on such a host the installer prints an AppArmor
|
|
profile that allows them for the Archie binaries only, to install with
|
|
`sudo`.
|
|
|
|
2. **Check it is up.**
|
|
|
|
```bash
|
|
systemctl --user status archied archie-state-store archie-gateway archie-ui archie-messaging
|
|
curl -s http://127.0.0.1:8485/health/detailed
|
|
```
|
|
|
|
3. **Open the dashboard** at <http://127.0.0.1:8484>. It binds loopback by
|
|
default; tunnel to it (`ssh -L 8484:127.0.0.1:8484 server`) or see
|
|
[deployments](deployments/README.md#running-the-dashboard) to expose it
|
|
with a token.
|
|
|
|
4. **Automate your first event** with
|
|
[Your first playbook](docs/guides/first-playbook.md): send a webhook, map
|
|
its fields, bind it to a workflow and watch the task run.
|
|
|
|
To write the config by hand instead, start from
|
|
[`deployments/standalone.toml`](deployments/standalone.toml) (no forge) or
|
|
another [deployment template](deployments/README.md).
|
|
|
|
## Develop
|
|
|
|
`task dev` starts every service with Vite hot reload at
|
|
<http://localhost:5173>, using [`deployments/dev.toml`](deployments/dev.toml).
|
|
`task check` is the quality gate; [AGENTS.md](AGENTS.md) lists its tools.
|
|
|
|
| Project skill | Use |
|
|
| --- | --- |
|
|
| [`/technical-prose-cleanup`](.github/skills/technical-prose-cleanup/SKILL.md) | Review technical writing in one module without changing behaviour. |
|
|
|
|
## Documentation
|
|
|
|
- [Your first playbook](docs/guides/first-playbook.md)
|
|
- [Deployment examples](deployments/README.md)
|
|
- [Release process](RELEASING.md)
|
|
|
|
Contributions follow [AGENTS.md](AGENTS.md).
|
|
|
|
## License
|
|
|
|
Copyright 2026 Sam Catlow. Licensed under the [Apache License, Version 2.0](LICENSE). Third-party attributions are in [NOTICE](NOTICE).
|