Cusimanse

Status: Beta — Research Framework & Runtime Kit

Cusimanse is actively being developed. Fork it, test it, run the reference experiments, report bugs, and submit pull requests. Expect APIs, recipes, documentation and integrations to evolve during beta.

AI use and responsible contribution: Cusimanse uses AI-assisted development and agentic AI as part of its research framework, documentation, analysis workflows and engineering process. AI-generated or AI-assisted output is not automatically authoritative, secure, correct, original or suitable for production use. Contributors are responsible for reviewing, testing and validating AI-assisted changes before submission. Do not rely on an AI system as the sole authority for security decisions, authorization, evidence interpretation or safety-critical actions. Use Cusimanse only for authorized research, respect applicable laws and policies, protect credentials and sensitive data, and keep execution within the project's declared policy and disposable-compute boundaries. Contributions should clearly identify material AI assistance where appropriate, preserve human accountability, and follow the repository's tests, review requirements and responsible-use expectations.

Declarative, agent-operated security research on disposable compute. Researchers declare intent and requirements; agents plan, select and analyze; the Go capability API and policy decide whether and how execution may occur.

Contract → requirements → prompt handoff → agent → capability resolution → Go runtime → policy/approval → Lima/QEMU → instrumentation/workload → evidence → analysis → independent verification → report → preservation → destroy.

Table of contents

• What Cusimanse is
• Architecture and authority boundary
• Researcher workflow
• Prompt library and agent handoff
• Host tooling and installation
• Gateways
• Instrumentation
• Observability
• Lima/QEMU and guest tooling
• Go capability API and commands
• Roles, Skills and learning loop
• Profiles and requirements
• Policy and safety
• Evidence and reproducibility
• Reference experiments
• Validation and integration testing
• Credits and open source community
• Repository map

What Cusimanse is

Layer	Responsibility	Source of truth
Contract	purpose, authorization, scope, acceptance	contracts/
Requirements	OS, isolation, workload, network, instrumentation	recipes/experiments/
Prompt library	agent-neutral handoff	prompts/experiments/
Operator guides	thin adapter handoff	prompts/operators/
Profiles	trusted reusable capabilities	recipes/profiles/
Runtime	resolution, policy, lifecycle, execution boundary	cmd/cusimanse/, internal/
Policy	authority and approval	policies/, internal/policy/
Containment	disposable compute	recipes/lima/, Lima/QEMU
Evidence	observations, provenance, verification	runs/<session-id>/

The agent cannot create trusted profiles, expand policy, mutate trusted recipes or execute an untrusted workload directly on the host.

Architecture and authority boundary

1. Declaration: contract + YAML requirements.
2. Handoff: shared experiment prompt plus optional operator guide.
3. Planning: Goose is the native reference operator; other agents use adapters.
4. Resolution: Go resolves requirements against registered profiles and fails closed on ambiguity.
5. Policy: Go evaluates authority and approval gates and audits decisions.
6. Execution: capabilities operate Lima/QEMU and fixed workload handlers.
7. Evidence: collect, hash, independently verify, report, preserve, then destroy disposable compute.

Boundary rule: the agent decides what research to do; Cusimanse decides whether and how it may execute.

Researcher workflow

1. Contract and requirements

Write contracts/<experiment>.md with research question, authorization, scope, acceptance criteria and safety constraints. Declare only requirements in recipes/experiments/<experiment>.yaml.

Example:

requirements:
  execution: disposable
  os: linux
  workload: npm-threat
  network: localhost-only
  instrumentation: [process, syscall, filesystem, network]

2. Bootstrap and deterministic validation

./scripts/install.sh
export PATH="$HOME/.local/bin:$HOME/go/bin:$PATH"
cusimanse doctor
cusimanse validate
cusimanse preflight
cusimanse policy validate
cusimanse test
cusimanse integration-test

3. Validate and run the Goose recipe

goose recipe validate recipes/npm-threat-001/recipe.yaml
goose recipe validate recipes/subrecipes/evidence-analysis.yaml
goose recipe validate recipes/subrecipes/verification.yaml
goose recipe validate recipes/subrecipes/report.yaml
goose run --recipe ./recipes/npm-threat-001/recipe.yaml --interactive

The recipe explicitly declares the summon platform extension. Summon provides delegation/orchestration only; it does not authorize execution.

4. Resolve and approve

cusimanse resolve npm-threat-001
cusimanse policy explain vm
cusimanse policy explain network
cusimanse policy check-all
cusimanse policy require vm --approved

5. Execute and finish

cusimanse --approved run npm-threat-001 <session-id>
cusimanse observability report <session-id>
cusimanse policy audit

Lifecycle: resolve → policy → provision → configure → instrument → execute → collect → verify → report → preserve → destroy.

Prompt library and agent handoff

The prompt is a handoff, not an authority layer and not a second recipe.

prompts/experiments/<experiment>.md       shared research handoff
prompts/operators/<operator>.md           thin operator guidance
recipes/experiments/<experiment>.yaml     requirements source of truth
recipes/<experiment>/recipe.yaml          Goose/runtime recipe
contracts/<experiment>.md                 authorization/scope source

For OpenCode, Hermes, Antigravity or Pi, provide the same contract, experiment YAML, recipe references, shared prompt and matching operator guide. The alternate operator may plan/delegate/analyze using its native features, but must invoke Cusimanse for capability execution. Unsupported capabilities are recorded as PARTIAL; adapters cannot mutate policy, profiles or trusted recipes.