What It Is
AIPermission is a local, single-user developer gateway. You register connector targets, keep their credential profiles inside an encrypted local database, and grant each AI token only the target/profile/action combinations it may use.
Potencia tu agente
Instalación del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
Aún no hay una versión empaquetada en el registro. Sigue el README del repositorio.
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador
AIPermission is a local, single-user developer gateway. You register connector targets, keep their credential profiles inside an encrypted local database, and grant each AI token only the target/profile/action combinations it may use.
Local-first permission gateway for AI agents with scoped connector access, human approval, audit trails, and encrypted local credentials.
| You keep control of | The AI gets |
|---|---|
| connector credentials | scoped MCP connector actions |
| project and token visibility | only visible target/profile references |
| Disabled, Prompt, or Always rules | execution after the effective rule is checked |
| local approval decisions | bounded action results and status |
| encrypted history and audit | no raw credential values |
All built-in connectors use the same project, target, credential profile, permission, approval, history, and audit pipeline. They are connector types rather than separate product modes. The generated connector catalog is the canonical current list and owns their capability summaries.
History and audit are encrypted, local, retention-controlled records for the active database. They are not an immutable external audit archive: configured retention can delete them, and deleting or replacing the local database removes its records.
Settings shows per-token connector request storage usage, result reservations, running work, and warnings before capacity is exhausted. Retained output counts toward storage limits even when no action is running. Review capacity and retention guidance rather than assuming that waiting alone frees retained records.
Local-only security boundary: run AIPermission on your own machine and keep its published Docker port bound to
127.0.0.1. It is not a remote multi-user service, LAN gateway, hosted control plane, or team RBAC system. Do not change the Compose bind to0.0.0.0; browser session, Host, CORS, and CSRF checks are defense in depth, not remote authentication.
AIPermission is pre-1.0 developer software. Read the project principles, threat model, and credential boundary before using it with important systems.
Security updates cover both gateway images and the MCP client's Node.js runtime. Use patched Node 22.23.4+, 24.22.1+, or 26.12.1+ for MCP, then restart the client after upgrading its interpreter. See the changelog and native dependency inventory, including the explicitly tracked SQLCipher upstream follow-up.
Without a gateway, AI-assisted operations often alternate between generated commands and pasted terminal output, or expose broad credentials directly to an agent. AIPermission provides a third path:
Connector credentials are used only inside the gateway. They are not returned through MCP or the normal REST API.

Requirements:
Start from a full Git checkout so version pinning and repository verification metadata remain available:
git clone https://github.com/aipermission/aipermission.git
cd aipermission
Start from published images:
docker compose -f docker-compose.release.yml pull
docker compose -f docker-compose.release.yml up -d
docker compose -f docker-compose.release.yml ps
curl --fail http://localhost:3210/health
Or build the current source tree:
docker compose up -d --build
docker compose ps
curl --fail http://localhost:3210/health
Open:
http://localhost:3210
Both Compose files publish only to 127.0.0.1. The backend is not exposed as
a separate host port. To use another local UI port:
AIPERMISSION_FRONTEND_PORT=3212 docker compose up -d --build
The release Compose file defaults to the version shipped in the checkout, so
these commands work unchanged in POSIX shells, PowerShell, and Command Prompt.
To run a different release, set AIPERMISSION_VERSION in your shell first.
Avoid opting into mutable latest when you need reproducible upgrades or
rollback.
export AIPERMISSION_VERSION=VERSION
docker compose -f docker-compose.release.yml up -d
Containers use the unless-stopped restart policy. See
Docker Runtime for Windows line endings, host
services, logs, and recovery guidance.
Published container images are currently built and validated for Linux AMD64. ARM64 hosts may use platform emulation or build from source, but native ARM64 images are not yet part of the supported release matrix. If startup or health verification fails, inspect the first bounded log sample before changing the gateway bind or deleting local data:
docker compose -f docker-compose.release.yml logs --tail=100
Projects organize one developer's local workspace; they are not team tenancy. See Projects. Project Vault is a separate project-scoped secret inventory and exact-session application flow; see Project Vault.
Install the official MCP bridge into a supported client:
npx -y @aipermission/mcp@VERSION setup \
--provider codex \
--scope user \
--name aipermission
The setup command asks for the API token with a hidden prompt, writes a config pinned to the package version that created it, and installs the native operator skill. Restart the AI client after installation.
Validate both paths without printing the token:
npx -y @aipermission/mcp@VERSION doctor --client codex --scope user
Supported client presets and source-development setup are documented in MCP Client Setup. The MCP tool contract is documented in MCP Tools.
Replace VERSION with the exact published version you intend to pin.
When reading a development branch, use the matching local package build instead
of copying a placeholder command.
Each token/target/profile/action permission resolves to one backend rule:
blocked: execution is deniedapproval_required: a pending request appears in the local UIalways_run: execution starts after current token, project, target,
credential, and action checks passThe UI presents these as Disabled, Prompt, and Always where appropriate. Use Prompt for real systems until the workflow is trusted. Temporary permissions can expire automatically. The global MCP Started/Stopped switch is an additional runtime boundary; saved Always rules do not bypass a stopped MCP gateway.
Pending approvals carry a context snapshot. Relevant token, permission, connector, target, credential, dependency, or action changes make the request stale and require a fresh approval. See MCP Permission Flow.
Important boundaries:
outcome_unknown before
another external attempt; see the
operator retry guidance.Canonical detail:
The UI can download and import encrypted .aipdb database files. The optional
self-hosted AIPermission Backup provider stores versioned encrypted database
streams without receiving the database password or encryption key. See
AIPermission Backup.
Recovery-grade database and transfer downloads require a browser with a native
streaming Save dialog so the UI never buffers an unknown-size encrypted
artifact in memory. Other bounded downloads can use the response-stream
fallback, which buffers at most 64 MiB. Browsers without response streaming
cannot safely download through this UI.
Version 0.2.0 established the connector-native database baseline. Important 0.1.x preview data can be imported with the local one-time migration helper; the normal gateway intentionally carries no pre-0.2 compatibility shim. See Database Migration.
Install the independently locked repository verification, frontend, and MCP packages, then run the standard gates:
npm ci --prefix scripts --workspaces=false
npm ci --prefix frontend --workspaces=false
npm ci --prefix packages/mcp --workspaces=false
make -f Makefile test
make -f Makefile build
make -f Makefile audit
The package-local lockfiles are canonical. Do not run npm install at the
repository root or create a root package-lock.json.
Full release validation:
make -f Makefile release-check
Useful package checks:
npm --prefix frontend run lint
npm --prefix frontend run format:check
npm --prefix frontend run test:coverage
npm --prefix frontend run test:e2e
npm --prefix packages/mcp run build
Read CONTRIBUTING and Development Testing before opening a pull request. Releases use RELEASE_CHECKLIST.md.
A normal connector adds:
backend/internal/connectors/<kind>/frontend/src/connectors/templates/<kind>/It must use the generic connector pipeline rather than adding its own permission, approval, history, audit, or MCP tool family. Runtime-backed capabilities require reviewed shared adapter contracts.
The complete contract, isolation rules, required frontend slots, credential schema requirements, and test checklist live in Add A Connector.
S3 operations preserve exact object keys; see the S3 transfer identity and mapping limits.
docs/index.md is the canonical navigation and ownership index. Use it for architecture, setup, security, API, connector, operator, and maintainer documentation.
AIPermission is pre-1.0, local-only developer software. Breaking changes may be made when they remove technical debt or strengthen the security model, and are documented in release notes. Only the latest tagged stable release receives security fixes.
The public roadmap is in docs/ROADMAP.md.
For a reproducible bug, open a bug report. For a security-sensitive finding, use the private reporting instructions in SECURITY.md, not a public issue. Design proposals can start in GitHub Discussions.
AIPermission is licensed under AGPL-3.0-only from v0.1.14 onward. See LICENSE.
Versions through v0.1.13 remain available under their original MIT license. Commercial use is allowed under AGPL terms; forks must not imply endorsement by the official AIPermission project.
Local-first permission gateway for AI agents with scoped connector access, human approval, audit trails, and encrypted local credentials.
Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
Aipermission se ejecuta localmente por stdio.
Última comprobación: 2026-10-28. Local-first permission gateway for AI agents with scoped connector access, human approval, audit trails, and encrypted local credentials.