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.proteanis 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_keyargument orGAMAI_TRUST_PUBKEY);status—verified,self_signed,unsigned,failedorunverified.
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:
trusthashes and verifies packages; it never executes a manifest. - Lease is a receipt, not authorization:
proteanmints 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:
lowuses bubblewrap;medium/highuse Docker with no network, dropped capabilities, read-only root and resource limits;criticalis denied unless a remote gVisor host is explicitly configured. - Bounded output:
proteancaptures 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=1is ignored when the policy saysaudit: true; audit failure becomesdeny/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
proteanmedium/high to untrusted users. - Trust score is heuristic:
trust_scoreis 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.