Skip to main content

gamAI plugins

Portable, dependency-light plugins for AI agents: policy evaluation, sandbox execution and team coordination. The same code is exposed as an MCP server, a CLI and a plain Python function, so it can run in Claude Code, opencode, Codex, Cursor, LangChain or a custom agent loop.

Status: 0.2.2 — small, explicit about its limits, and hardened against the failures found in an external-style audit. protean is a namespace sandbox, not a VM and not a hardened multi-tenant boundary.

Plugins

Plugin What it does Default
trust Evaluates allow/deny policy with audit; verifies package integrity (never executes a manifest). missing/invalid policy ⇒ deny
protean Runs a command in a sandbox with a lease receipt, risk-routed substrates and JSONL evidence. low = bubblewrap
team Deterministic goal split, isolated clone, persistent state, at most one optional LLM call per task. deterministic fallback

Install

pip install -e .
# optional Ed25519 verification for trust
pip install -e '.[crypto]'

Linux is recommended for protean:

sudo apt-get install bubblewrap   # risk=low
# Docker is optional; risk=medium/high use docker runc

risk=low mounts a minimal read-only root (/usr/bin, /usr/sbin, /usr/lib, /usr/share, /bin, /sbin, /lib, /lib64). /etc is a tmpfs with an allowlist of non-secret files; /etc/shadow, gshadow, sudoers, host SSH keys and private TLS keys are not exposed. /root, /home, /opt, /var and /run are not mounted. /tmp is a 32 MiB tmpfs, and prlimit caps address space and process count when available.

The allowlist checks only the first executable token. Shell syntax can run other binaries present in the mounted root. The sandbox, not the allowlist, is the security boundary. Available binaries depend on the substrate: the default Docker image has sh and python3, but not bash, git or node; use a custom PROTEAN_IMAGE if you need them.

MCP

{
  "mcpServers": {
    "gamai-plugins": {
      "command": "gamai-plugins-mcp"
    }
  }
}

The server exposes six namespaced tools:

trust_managed_policy
trust_marketplace_verify
protean_run
team_create
team_dispatch
team_status

CLI

gamai-plugins list
gamai-plugins call trust managed_policy '{"action":"load"}'
gamai-plugins call protean run '{"cmd":"echo hi","risk":"low","timeout_s":5}'
gamai-plugins call team team_create '{"goal":"review this change","agents":2}'
gamai-plugins mcp

Or the per-plugin entry points:

gamai-trust managed_policy '{"action":"check","tool":"shell"}'
gamai-protean run '{"cmd":"uname -a","risk":"low"}'
gamai-team team_status '{"team_id":"team-..."}'

CLI exit code is non-zero when a tool returns ok:false or a trust decision is deny, so shell/CI gates can use it.

Python

from gamai_plugins.cli import call

print(call("protean", "run", {"cmd": "echo hi", "risk": "low", "timeout_s": 5}))

Policy and integrity semantics

trust_managed_policy is an evaluator, not an enforcement point. The caller must enforce the returned decision. A valid policy without default is deny; deny rules win. Paths are normalized and shell segments are evaluated separately.

trust_marketplace_verify returns:

  • integrity_ok — every expected file matches and there is no unexpected, truncated or symlinked content;
  • trusted — integrity is complete and the signature verifies with a pinned key (public_key argument or GAMAI_TRUST_PUBKEY);
  • status — verified, self_signed, unsigned, failed or unverified.

A self-signed manifest is not trusted. Without a manifest the result is unverified, not a silent pass. See docs/MANIFEST.md for the canonical signing form and scripts/sign_manifest.py.

Team semantics

team_create creates a shared clone (not a source worktree) with core.hooksPath pointing at an empty directory, so an untrusted repository cannot execute hooks later. State is written before isolation, so a slow clone does not leave a registered workspace without state.

team prompts and role hints are currently Bosnian. That is intentional, not a translation layer; make it configurable if you need another language. Dispatch is serialized per team: the LLM call happens while the team lock is held, so concurrent dispatches wait rather than racing state.

Configuration

Variable Used by Meaning
GAMAI_POLICY trust policy JSON; default ~/.config/gamai/trust/policy.json
GAMAI_AUDIT trust audit JSONL; default ~/.local/state/gamai/trust/audit.jsonl
GAMAI_AUDIT_DISABLE trust 1 disables audit only when the policy does not require audit
GAMAI_TRUST_PUBKEY trust pinned Ed25519 key (PEM, 64 hex, or base64 raw 32 bytes)
GAMAI_HOME trust base config dir; default ~/.config/gamai
GAMAI_STATE trust base state dir; default ~/.local/state/gamai
PROTEAN_HOME protean data dir; default ~/.config/gamai/protean
PROTEAN_IMAGE protean Docker image for medium/high; default python:3.12-alpine
PROTEAN_HIGH_REMOTE protean 1 allows high risk to use the configured remote gVisor
PROTEAN_REMOTE_HOST protean optional remote host for critical + gVisor
PROTEAN_REMOTE_PORT, PROTEAN_REMOTE_KEY, PROTEAN_REMOTE_USER protean SSH details for the remote substrate
PROTEAN_KNOWN_HOSTS protean SSH known_hosts; default ~/.ssh/known_hosts
PROTEAN_SSH_STRICT protean yes, accept-new (default) or no
GAMAI_TEAM_STATE_DIR team state dir; default ~/.local/state/gamai/teams
GAMAI_TEAM_WORKTREES team workspace dir; default ~/.cache/gamai/teams
GAMAI_TEAM_REPO team default repo for isolation when repo is omitted
GAMAI_TEAM_LLM_BUDGET team max LLM calls per team; default 50
GAMAI_TEAM_LLM_TIMEOUT team per-call timeout; default 40 s
GAMAI_LLM_URL team optional HTTPS endpoint for one LLM call per task; HTTP only for loopback
GAMAI_LLM_TOKEN team optional X-Token sent to that endpoint
GAMAI_TEAM_AGENT team default backend name; default agent

No secret is stored in this repository. protean creates a per-install lease.key at runtime with mode 600.

Safety model

  • Trust is fail-closed: missing/invalid policy, invalid manifest or a required audit failure yields deny/failure.
  • Manifest is data: trust hashes and verifies packages; it never executes a manifest.
  • Lease is a receipt, not authorization: protean mints and verifies the lease in the same process. It binds command/genome/TTL for evidence, but it is not an external policy decision.
  • Substrate routing: low uses bubblewrap; medium/high use Docker with no network, dropped capabilities, read-only root and resource limits; critical is denied unless a remote gVisor host is explicitly configured.
  • Bounded output: protean captures at most 64 KiB per stream and returns at most 8,000 characters; evidence runs are pruned to the newest 200.
  • Audit cannot be disabled when required: GAMAI_AUDIT_DISABLE=1 is ignored when the policy says audit: true; audit failure becomes deny/audit_failed.
  • Team is not an authorization boundary. It coordinates work; the backend decides what it executes. LLM redirects are not followed and public plain HTTP is refused; the configured HTTPS origin still receives the token by design.
  • Docker socket is root-equivalent. Do not expose protean medium/high to untrusted users.
  • Trust score is heuristic: trust_score is a documented 0–100 heuristic, not a cryptographic proof.

Read SECURITY.md and THREAT_MODEL.md before using this in production.

Development

python -m unittest discover -s tests -v
python -m gamai_plugins.mcp --selftest
python scripts/smoke_mcp.py

The tests do not need network access, Docker, or an LLM. protean low-risk tests use bubblewrap when available; Windows runs the same suite without it.

License

MIT.

Metadata

Release files for gamai-plugins 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gamai-plugins 0.2.2
File Size Uploaded Provenance Actions
gamai_plugins-0.2.2.tar.gz 42.7 kB Without provenance Details for gamai_plugins-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gamai-plugins 0.2.2
File Interpreter ABI Platform Actions
gamai_plugins-0.2.2-py3-none-any.whl Python 3 none any Details for gamai_plugins-0.2.2-py3-none-any.whl

Total release size: 80.5 kB

Release files / gamai_plugins-0.2.2.tar.gz

Download URL gamai_plugins-0.2.2.tar.gz
Size 42.7 kB
Tags Source
SHA-256 checksum
How to use checksums
240afcd840821130c09c3369766856a826bde943fe5d754314c916ed205bb19c
BLAKE2b-256 checksum
How to use checksums
1fbb82af4fe1861c1d049b2708115137386f3cb85795b9c8d03ec0da027efcf3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / gamai_plugins-0.2.2-py3-none-any.whl

Download URL gamai_plugins-0.2.2-py3-none-any.whl
Size 37.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
548beabed99b5e25b473302213f73d9ad7ba90eac6b702d9dc8ab9140841d5a9
BLAKE2b-256 checksum
How to use checksums
32d4a03e239b7900cbb471a4915b13f712b5bc5d482318b5a6eae2d2910196fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for gamai-plugins 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page