declaragent

v0.6.0 on npm · Apache-2.0

An agent to build and manage
fleets of agents for enterprise.

Talk to declaragent. Describe the fleet you need — it proposes agent.yaml files, skills, event sources, channels, peer wiring; you confirm; it writes them. One CLI then deploys the fleet, streams metrics, and rolls out canaries. Prometheus, OpenTelemetry, circuit breakers, rate limits, dispatch DLQ — all built-in. Declaragent itself is an agent, built on the same core you ship to production.

$ npm i -g @declaragent/cli Read the docs →

Apache-2.0 · 13 packages · Node ≥ 18 · No vendor lock-in

~/my-agent — declaragent 
█

Built with itself

declaragent is an agent.

Launch the REPL, you're talking to an agent built on @declaragent/core — the same runtime, same tools, same audit chain, same permission gate you'd use to build your own. One core, many agents. No second implementation, no "CLI-only" features locked out of your production path.

core @declaragent/core engine · tools · audit · permissions
agent #1 declaragent REPL the CLI you install — itself an agent
agent #2…N your agent.yaml every agent you declare + ship

Same Tool contract. Same permission gate. Same audit sink. If your agent can do it, so can the CLI. If the CLI does it, your agent can inherit it.

Converse → fleet

Describe what you need. Review the plan. Apply.

Start the REPL with DECLARAGENT_BUILDER=on declaragent. Tell it what the fleet should do. It proposes a complete change-set — agent.yaml, skills, event sources, channel bindings, peer entries. You review, /yes to apply or /edit to adjust. Every apply is git-rollback-safe and recorded to the hash-chained audit log. 14 builder tools, plan-confirm-execute, scope + secret guards — all shipped in @declaragent/[email protected].

01 Describe "Triage new GitHub issues, hand severe ones to a reviewer agent, notify #oncall."
02 Propose Two agents + peer wiring + webhook source + Slack channel — diff shown, no secrets written.
03 Apply & deploy /yes → files written · declaragent fleet run → online.

Not a wizard. Not a template gallery. A conversation with an agent that understands the runtime it's authoring for — because it runs on the same core.

Take the 15-minute tour → Builder reference

First principles — honest status

Five pillars. Single-machine ✅. Enterprise 🟡.

Single-machine production is fully shipped. Enterprise — multi-host, SSO-bridged, SIEM-exported, GitOps-rendered — is 10–14 engineer-weeks of integration work, not a rewrite. Full evidence: FIRST_PRINCIPLES_VALIDATION.md.

1 · Define agents

agent.yaml identity + Markdown skills + tool allowlists + inbound/outbound channels + typed peers. ✅ single-machine · 🟡 enterprise (typed capabilities, SSO-bridged permissions pending).

2 · Deploy + monitor

up / ps / logs / down, Prometheus on :9464, OpenTelemetry auto-enable, circuit breakers, rate limits, canary deploys. ✅ single-machine · 🟡 enterprise (no managed control plane, audit is local SQLite).

3 · Independent agents + delegation

Memory + Kafka RPC transports, pending-registry correlation, version-skew detection, fleet-e2e tests, nightly CI on Redpanda. ✅ single-machine · 🟡 enterprise (Kafka soak pending, NATS/SQS/AMQP/MQTT transports missing).

4 · Tools + MCP

8 built-in tools (Read, Write, Edit, Bash, Glob, Grep, Agent, SendMessage) + MCP stdio/HTTP/SSE/streamable-HTTP + OAuth 2.1 PKCE. ✅ single-machine · 🟡 enterprise (no per-tool rate limit, no MCP auto-recovery).

5 · Conversational builder

14 builder tools, 300-line authoring system prompt, plan-confirm-execute, git-backed rollback, scope + secret guards, fleet-e2e test. ✅ single-machine · 🟡 enterprise (no live-LLM regression fixture, manual env/deploy hand-off by design).

Honesty clause

We publish AGENTS.md and FIRST_PRINCIPLES_AUDIT.md with file:line evidence for every ✅ and 🟡. If it says it works, it has tests. If it says 🟡, the gap is named.

Capabilities

What you can add to an agent.

Every block below is declarative in agent.yaml and installable through the CLI. No hidden console, no vendor dashboard.

tools

Built-in tools

Read, Write, Edit, Bash, Glob, Grep, Agent, SendMessage. File-system grounded. MCP server tools load on top. 

tools:
  defaults: [Read, Glob, Grep, Bash]
Tools reference →
skills

Markdown skills

Prompts + input schema in one Markdown file with frontmatter. {{var}} interpolation. Tiered discovery (user / project / plugin). 

skills:
  - skills/review-pr.md
Skills reference →
plugins

npm plugins

Bundle skills, tools, channels, sources. Consent-gated permission grants on install. Versioned via changesets. 

$ declaragent plugin install \
    @declaragent/plugin-github
Plugin system →
mcp

MCP servers

First-class Model Context Protocol support — stdio + HTTP. Tools, resources, prompts. One-command registration. 

$ declaragent mcp add postgres \
    --command psql-mcp
MCP reference →
sources

Event sources

Cron, webhook, file-watch, Kafka, NATS, SQS, AMQP, MQTT. DLQ + replay + idempotency + rate limiting — declaratively. 

$ declaragent source add webhook \
    gh-events --config-file ./hook.yaml
Source adapters →
channels

Chat channels

Slack, Telegram, Discord, WhatsApp. Outbound rate limits, send idempotency, per-user session context, BlockKit / Markdown rendering. 

channels:
  - id: slack-prod
    type: slack
Channel registry →
tenancy

Multi-tenant isolation

One daemon, many tenants. Per-tenant quotas, extension scopes, residency tags, tenant-stamped buses. 

$ declaragent tenants show acme-prod
$ declaragent tenants diff
Multi-tenant guide →
secrets

Secrets rotation

Vault, AWS Secrets Manager, GCP Secret Manager, K8s, env. TTL cache, audit on every resolve, rotation monitor. 

$ declaragent secrets rotate \
    vault:kv/acme/gh-token
Secrets reference →
audit

Hash-chained audit

Every tool call, channel send, tenant boundary, secret access. SHA-256 chain verify. GDPR erase by user or correlationId. 

$ declaragent audit verify
$ declaragent audit erase --user U123
Audit format →
permissions

Permission gate

Four modes: default (prompt per call), plan (dry-run), bypass (trusted), auto (auto-approve allow-list). Sandboxing on file + shell. 

$ declaragent --mode plan
$ declaragent --mode auto
Permission modes →
observability

Metrics + traces

Prometheus exporter with per-tenant labels. OpenTelemetry spans for every turn + tool call. Structured logs with correlationId threading. 

observability:
  prometheus: { port: 9464 }
  otel: { endpoint: $OTEL_URL }
Grafana setup →
fleets

Multi-agent fleets

One fleet.yaml declares N agents + shared peer table. Inter-agent RPC, rolling / all-or-nothing deploy, version-skew detection. 

$ declaragent fleet new acme-fleet
$ declaragent fleet run
Fleet reference →

Lifecycle

One CLI. Every step of the agent lifecycle.

No separate tools for init vs. deploy vs. ops. The same binary you install on your laptop runs in CI and talks to the daemon in production.

01

Build

declaragent init --fleet acme
cd acme

DECLARAGENT_BUILDER=on declaragent
> build a fleet that triages GH
>   issues and hands severe ones
>   to a reviewer agent
/yes

Scaffold a fleet, then converse to shape it. Templates still work.

02

Configure

declaragent plugin install \
  @declaragent/plugin-github

declaragent source add webhook \
  gh-events --config-file ./hook.yaml

declaragent mcp add postgres \
  --command psql-mcp

Add plugins, event sources, MCP servers, channels. Consent-gated.

03

Operate

declaragent daemon
declaragent events list --last 20
declaragent dlq redrive \
  --source webhook:gh-events <id>
declaragent audit verify
declaragent tenants show acme-prod

Run locally or as a daemon. Observe, replay, audit, debug.

04

Deploy

declaragent deploy gcp-cloud-run \
  --project acme --region us-central1

declaragent fleet deploy \
  --target cloud-run
declaragent fleet deploy --rollback

Single agent or whole fleet. Rolling, health-gated, rollback-ready.

Enterprise primitives

Built for the ops team, not just the prompt engineer.

Audit & compliance

Every tool call, channel send, tenant boundary, and secret resolve is recorded to a SHA-256 hash chain. audit verify detects tampering; audit erase --user tombstones in a GDPR-clean pass.

Multi-tenant isolation

One tenants.yaml declares quotas, residency, extension allow/deny, and per-tenant secret scopes. The event bus is tenant-stamped; cross-tenant writes fail closed with a typed error.

Secrets rotation

Native providers for Vault, AWS Secrets Manager, GCP Secret Manager, K8s, and env. TTL cache + rotation monitor. Every resolve writes a secret_access audit record.

Permission gate

Four runtime modes — default (prompt per call), plan, bypass, auto (allow-list). File-system sandboxing, per-tool allow/deny globs, escalation on denial.

Observability

Prometheus exporter with tenant_id constLabels baked in. OpenTelemetry spans thread through every turn, tool call, and RPC hop. Structured logs keyed on correlationId.

Deploy automation

Cloud Run deploy templates generated from agent.yaml. Fleet deploys support rolling / all-or-nothing / per-agent with health-gated rollback. Every deploy records a version; one flag reverts.

Advanced — try in your browser

Paste a fleet.yaml. Run the production validator without installing anything.

This is the same validation logic that ships in @declaragent/cli, ported verbatim. Dangle a peer, duplicate a capability, reference a missing deploy target — the findings appear inline, offline, with no network hop.

fleet.yaml
Findings
  • Click Validate to run.

Install three ways.

curl -fsSL https://declaragent.dev/install.sh | sh

Then — converse your fleet into existence:

declaragent init --fleet acme
cd acme
DECLARAGENT_BUILDER=on declaragent

New to Declaragent? Take the 15-minute conversational tour →

Read the docs → Source on GitHub