{"id":49773294,"url":"https://github.com/pknull/servitor","last_synced_at":"2026-05-11T14:09:09.383Z","repository":{"id":354298964,"uuid":"1175088259","full_name":"pknull/servitor","owner":"pknull","description":"Network task executor with MCP tools and LLM reasoning for Thallus","archived":false,"fork":false,"pushed_at":"2026-04-28T01:26:54.000Z","size":513,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-28T02:25:22.865Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pknull.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-07T07:56:23.000Z","updated_at":"2026-04-28T01:26:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pknull/servitor","commit_stats":null,"previous_names":["pknull/servitor"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/pknull/servitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pknull%2Fservitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pknull%2Fservitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pknull%2Fservitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pknull%2Fservitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pknull","download_url":"https://codeload.github.com/pknull/servitor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pknull%2Fservitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32898079,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-11T14:09:04.211Z","updated_at":"2026-05-11T14:09:09.372Z","avatar_url":"https://github.com/pknull.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Servitor\n\nServitor is an egregore-connected task executor. It owns MCP clients directly, can delegate to external A2A agents, and publishes execution results back to the feed through the local egregore node.\n\nServitor is the **hands** of Thallus:\n\n- it does not own user-facing conversation\n- it does not own task decomposition or planning\n- it executes pre-planned work, enforces authority and scope, and reports results\n\n## Quick Start\n\nBuild and install:\n\n```bash\ncargo build --release\ncp target/release/servitor ~/.local/bin/\n```\n\nCreate local config and authority files:\n\n```bash\ncp servitor.example.toml servitor.toml\nservitor init\ncp authority.example.toml ~/.servitor/authority.toml\n```\n\nRun the daemon:\n\n```bash\nservitor run\n```\n\nExecute a structured direct task locally:\n\n```bash\nservitor exec '[{\"name\":\"shell__execute\",\"arguments\":{\"command\":\"pwd\"}}]'\n```\n\nDaemon and hook modes refuse work unless `authority.toml` is present or `--insecure` is set explicitly for local development. Local `servitor exec` runs authorize as the servitor's own egregore identity when authority is configured.\n\n## Documentation\n\n- Docs index: [docs/README.md](docs/README.md)\n- Protocol and message lifecycle: [docs/protocol.md](docs/protocol.md)\n- Configuration reference: [docs/configuration.md](docs/configuration.md)\n- Operational guidance: [docs/operations.md](docs/operations.md)\n- HTTP and OpenAPI boundary: [docs/api/README.md](docs/api/README.md)\n\n## Architecture\n\n```text\n┌─────────────────┐     ┌─────────────────────────────────────────────┐\n│    Egregore     │────▶│                  SERVITOR                    │\n│   (messages)    │◀────│                                              │\n│                 │     │  ┌─────────────────────┐                    │\n│  - task         │     │  │   MCP Client Pool   │                    │\n│  - task_offer   │     │  │  ┌─────┐ ┌─────┐   │                    │\n│  - task_assign  │     │  │  │stdio│ │http │   │                    │\n│  - task_result  │     │  │  └──┬──┘ └──┬──┘   │                    │\n│  - profile      │     │  └─────┼───────┼──────┘                    │\n└─────────────────┘     │   ┌────┴───────┴────────────────────────┐  │\n                        │   │          Scope Enforcer             │  │\n                        │   │   (allowlist/blocklist per MCP)     │  │\n                        │   └─────────────────────────────────────┘  │\n                        └─────────────────────────────────────────────┘\n```\n\n### Two-Plane Model\n\n| Plane | Purpose | Examples |\n|-------|---------|----------|\n| **Communication** | Task sourcing and result publication | Egregore, A2A |\n| **Tool** | Execution capabilities | MCP servers, A2A agents |\n\nPlanning and user interaction belong to Familiar, not Servitor.\n\n## Operating Modes\n\n| Mode | Command | Purpose |\n|------|---------|---------|\n| Direct exec | `servitor exec '\u003cjson tool calls\u003e'` | Local one-shot execution of pre-planned tool calls |\n| Daemon | `servitor run` | SSE subscription, cron, MCP notification routing, and profile publishing |\n| Hook | `servitor run --hook` | Read one egregore `task` envelope from stdin |\n| Info | `servitor info` | Show identity, capabilities, and authority state |\n\n## Protocol Overview\n\nServitor currently uses two related task paths:\n\n1. Direct, hook, cron, and MCP notification execution:\n   `task -\u003e optional task_claim -\u003e task_result`\n2. SSE-coordinated network execution:\n   `task -\u003e task_offer -\u003e task_assign -\u003e task_started -\u003e task_status/task_failed -\u003e task_result`\n\nAdditional audit and observability messages:\n\n- `servitor_profile`: capability advertisement and heartbeat\n- `servitor_manifest`: planner-facing executor manifest derived from local tool discovery\n- `environment_snapshot`: target-specific planner context, optionally enriched by configured probe tool calls\n- `task_offer_withdraw`: offer TTL expired before assignment\n- `task_ping`: request a status update from an active execution\n- `auth_denied`: published when offer or assignment authorization fails\n- `trace_span`: opt-in distributed execution tracing\n- `notification`: outbound notification payloads\n\nSee [docs/protocol.md](docs/protocol.md) for the lifecycle, auth gates, and message semantics.\n\n## Configuration Highlights\n\nKey config surfaces live in [servitor.example.toml](servitor.example.toml):\n\n- `[mcp.*]`: tool transports, timeouts, and scope enforcement\n- `[a2a.*]`: external agent clients\n- `[a2a_server]`: inbound A2A server\n- `[task]`: offer, assignment, start, ETA, and ping timeouts\n- `[agent]`: execution timeout plus opt-in `trace_span` publishing\n- `[heartbeat]`: profile cadence plus opt-in runtime monitoring fields\n- `[profile]`: planner-facing roles, labels, and deployment target summaries\n- `[egregore]`: egregore endpoint and SSE subscription\n\nConfigured `profile.targets[*].snapshot_tool_calls` let a servitor publish live\ntarget snapshots without embedding planner logic in the executor. The probe\ncalls are operator-curated structured tool calls, not ad hoc prompts.\n\nThe `[egregore.group]` and `[comms.http]` sections are reserved configuration on this branch. They are parsed by the config schema but are not wired into the current runtime.\n\n## Scope Enforcement\n\n- Block patterns take precedence over allow patterns\n- Patterns support glob syntax: `*`, `**`, `?`\n- Scoped patterns bind a tool name to an argument pattern, for example `execute:/etc/*`\n- Per-task `scope_override` can only further restrict access; it cannot widen a tool's configured scope\n\n## Deployment\n\n- Sandboxed sidecar deployment guide: [docs/deployment/containerization.md](docs/deployment/containerization.md)\n- Example systemd units: [examples/systemd/](examples/systemd/)\n- Example A2A mesh: [examples/a2a-mesh/](examples/a2a-mesh/)\n\n## HTTP and OpenAPI\n\nServitor does not expose a stable inbound HTTP control API on this branch, so it does not currently ship its own OpenAPI document. It talks to Egregore's HTTP API and to MCP servers over HTTP as a client. See [docs/api/README.md](docs/api/README.md) for the exact boundary.\n\n## Development\n\n```bash\ncargo test\ncargo check\ncargo build --release\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpknull%2Fservitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpknull%2Fservitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpknull%2Fservitor/lists"}