Skip to content

MANIFEST-QUICK-REF.md

Latest commit

 

History

History
181 lines (155 loc) · 10.3 KB

MANIFEST-QUICK-REF.md

File metadata and controls

181 lines (155 loc) · 10.3 KB
Raw

Manifest Quick Reference

Copy-paste patterns for common agentcli manifests.

Shell task with schedule

{
  "version": "0.1",
  "workflows": [{
    "id": "my-workflow",
    "name": "My Workflow",
    "tasks": [{
      "id": "my-task",
      "name": "My Task",
      "shell": { "program": "bash", "args": ["/path/to/script.sh"] },
      "target": { "session_target": "shell" },
      "schedule": { "cron": "0 9 * * *", "tz": "America/New_York" },
      "delivery": { "mode": "announce-always", "channel": "telegram", "to": "CHAT_ID" },
      "reliability": { "overlap_policy": "skip" }
    }]
  }]
}

Agent task (isolated session)

{
  "id": "email-check",
  "name": "Check Email",
  "prompt": "Check inbox for important messages. Summarize anything urgent.",
  "target": { "session_target": "isolated" },
  "schedule": { "cron": "0 9 * * *", "tz": "America/New_York" },
  "delivery": { "mode": "announce-always", "channel": "telegram", "to": "CHAT_ID" },
  "reliability": { "overlap_policy": "skip" }
}

Chained tasks (parent triggers child)

{
  "tasks": [
    {
      "id": "collect-data",
      "name": "Collect Data",
      "shell": { "program": "python3", "args": ["collect.py"] },
      "target": { "session_target": "shell" },
      "schedule": { "cron": "0 6 * * *", "tz": "America/New_York" }
    },
    {
      "id": "process-data",
      "name": "Process Data",
      "shell": { "program": "python3", "args": ["process.py"] },
      "target": { "session_target": "shell" },
      "trigger": { "parent": "collect-data", "on": "success" },
      "delivery": { "mode": "announce-always", "channel": "telegram", "to": "CHAT_ID" }
    }
  ]
}

Key fields

Field Required Description
id yes Unique task identifier (alphanumeric + hyphens)
name yes Human-readable name
shell.program for shell tasks Executable to run
shell.args for shell tasks Arguments array
prompt for agent tasks Natural language instruction
target.session_target yes shell, isolated, or main
schedule.cron for roots Cron expression
schedule.tz optional IANA timezone (default: UTC)
trigger.parent for children Parent task id
trigger.on for children success, failure, or complete
delivery.mode optional announce-always, announce (error-only), none
delivery.channel optional telegram, etc.
delivery.to optional Channel-specific target (chat ID)
reliability.overlap_policy optional skip, queue, allow
runtime.timeout_ms optional Local or backend execution timeout in milliseconds
verify.shell optional Post-completion verification command
authorization_proof_profiles[].verify.required optional Verification policy; every non-none proof is verified regardless
authorization.request.include optional Array of include fields for OPA request (actor, step_up)
subject.attributes optional Actor metadata object (org_id, on_behalf_of_user_id, delegation_grant_id, run_id, agent_id, verification_ref, verification_level)
authorization_proof_profiles[].jwks_uri optional JWKS endpoint URI for JWT key discovery and caching
authorization_proof_profiles[].public_key optional Inline public key for JWT verification

Safety rules

  • agentcli exec --dry-run is a static preview. It performs no approval consumption, proof command, provider call, sandbox probe, credential materialization, signing, evidence, postcondition, or audit write.
  • Manual grants are single-use and bind the canonical manifest plus the full effective execution configuration. Approver scope and timeout are enforced. Unexpected unsigned grants are rejected.
  • jwt, detached-signature, and certificate proofs must verify cryptographically and bind the canonical manifest. Use method: "none" for an intentionally unverifiable declaration.
  • Requested sandbox or network restrictions fail closed if the local host cannot enforce them.
  • Child processes inherit only a small operational allowlist. Every other ambient variable requires explicit shell.env declaration or identity-provider materialization.
  • agentcli run skips disabled tasks and their branches.
  • Scheduler apply rejects inline shell.env and shell.stdin; durable credentials belong in runtime identity providers.

Session targets

  • shell: Runs a command. Fast, predictable. Use for scripts and pipelines.
  • isolated: Fresh agent session per run. Waits for response. Use for agent tasks needing output capture.
  • main: Persistent agent session. Sync by default (waits for response). Use for quick tasks that benefit from conversation context.

Delivery modes

  • announce-always: Deliver on success and error.
  • announce: Deliver on error only.
  • none: Silent.

Examples

v0.1 -- no auth, good starting points

Manifest Tasks Description
hello-world.json 2 Minimal: scheduled task + triggered follow-up
shell-workflow.json 2 Shell command with agent escalation on failure
public-bot-health.json 2 Health check with delivery
public-report-publish.json 3 Approval-gated publish flow
public-shell-failure-triage.json 1 Failure triage with on_failure handler
identity-contract.json 2 Contract enforcement without identity profiles

v0.2 -- with identity, credentials, and trust

Manifest Tasks Description
stripe-ops.json 3 Stripe CLI: scoped API keys with downscope hierarchy
stripe-projects.json 3 Stripe Projects: two identity profiles, different trust levels
full-stack-deploy.json 5 Deploy pipeline: Stripe + Prisma + Fly.io with three identities
ansible-ops.json 5 Ansible: inventory check, fact gathering, dry run, approval-gated apply, agent drift report
kubectl-ops.json 5 Kubernetes: RBAC-scoped kubeconfig with strict trust
terraform-ops.json 4 Terraform: plan/apply with approval gate
gh-ops.json 4 GitHub CLI: PR, issue, and release workflows
docker-ops.json 5 Docker: build, push, deploy with registry credentials
aws-ops.json 5 AWS: STS assume-role with S3/Lambda/CloudWatch
gcloud-ops.json 4 GCP: workload identity with GKE/Cloud Run
ssh-remote.json 5 SSH: remote execution with key-based identity
vercel-ops.json 7 Vercel: deployments, domains, preview→promote pipeline with approval, health verify
neon-ops.json 7 Neon: branch management, connection strings, operations monitoring with admin/readonly split
supabase-ops.json 7 Supabase: migrations, edge functions, secrets audit with deploy pipeline
psql-ops.json 4 PostgreSQL: queries, migrations with strict trust and approval
npm-ops.json 5 npm: publish, audit, update workflows
git-ops.json 5 Git: commit, push, tag with signing identity
curl-api.json 3 Generic API calls with bearer auth
flyctl-ops.json 1 Fly.io deploy with env-bearer
cloud-workload.json 1 Cloud workload identity patterns
oidc-service-auth.json 1 OIDC client credentials flow
identity-v2.json 2 Minimal v0.2 identity with env-bearer
trust-enforcement.json 3 Trust level enforcement with contract boundaries
authorization-proof.json 1 JWT-based authorization proof verification
stripe-identity-step-up.json - Identity step-up verification with OPA policy and testing guide
rh-ops.json 85 RequestHub CLI: reads (status/health/stats/logs/events/images/db/argocd/customers) and mutations (build/deploy/migrate/seed/secrets/customer lifecycle) across three identity profiles with approval gates on all 37 mutating tasks

Commands

agentcli validate manifest.json          # Check for errors
agentcli compile manifest.json --target openclaw-scheduler --explain
agentcli apply manifest.json --db scheduler.db --scheduler-prefix ./scheduler --dry-run
agentcli apply manifest.json --db scheduler.db --scheduler-prefix ./scheduler --adopt-by name
agentcli exec manifest.json task-id      # Run a task locally
agentcli exec manifest.json task-id --approval-id <id>   # Target a specific pending approval
agentcli schema manifest                 # Draft 2020-12 JSON Schema
agentcli schema manifest --legacy        # Legacy agentcli descriptor
agentcli describe commands --json        # All CLI commands

Approvals (local gate)

Tasks with approval.policy: "manual" refuse to run via agentcli exec unless a matching, unconsumed approval record exists. Grants are signed by default, single-use, constrained by approver_scope and timeout_s, and bound to the canonical manifest and complete effective execution configuration. Unexpected unsigned grants fail; --signer none is the explicit unsigned mode. --dry-run is static and does not consume or enforce the gate.

agentcli approve manifest.json task-id --by alex --reason "tuesday deploy" --ttl-s 3600
agentcli approvals list                         # all records, latest first
agentcli approvals list --status pending        # filter by status
agentcli approvals revoke <approval-id> --by alex --reason "changed plans"

Durable multi-actor cron-triggered approvals remain owned by openclaw-scheduler; the local mechanism is for direct exec on a single machine.