Content
# Impri — Approval Inbox for AI Agents
> The imprimatur for your AI agents. Watchers watch the world, the Approval
> Inbox holds the agent's hands until a human says yes.
## Quickstart
### Docker Compose (< 5 minutes)
```bash
git clone https://gitlab.com/sekera.radim/impri.git
cd impri
docker compose up
```
Open **http://localhost:8080** in your browser.
On first start the server prints the bootstrap Admin API key to the logs:
```
╔══════════════════════════════════════════════════════╗
║ IMPRI — FIRST RUN BOOTSTRAP ║
╠══════════════════════════════════════════════════════╣
║ Admin API Key: im_... ║
║ Project ID: proj_... ║
║ Store this key securely — it will not be shown again.║
╚══════════════════════════════════════════════════════╝
```
Copy the key, paste it into the login screen, and you're in.
### Dev mode (hot-reload)
**Terminal 1 — server:**
```bash
cd server
npm install
npm run dev
# Server starts on http://localhost:8484
```
**Terminal 2 — UI:**
```bash
cd ui
npm install
npm run dev
# UI starts on http://localhost:5173
# /v1 requests are proxied to localhost:8484
```
## API at a glance
Base URL: `http://localhost:8484/v1`
Auth: `Authorization: Bearer im_<key>`
| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/actions` | Push a new action for approval |
| GET | `/v1/actions` | List actions (`?status=pending&q=…&kind=…&since=…`) |
| GET | `/v1/actions/:id` | Get action detail + decision |
| POST | `/v1/actions/:id/decision` | Approve or reject (single) |
| POST | `/v1/actions/bulk-decision` | Approve or reject up to 50 actions at once |
| POST | `/v1/actions/:id/result` | Report execution result |
| GET | `/v1/openapi.json` | OpenAPI spec |
### Push an action (curl example)
```bash
curl -X POST http://localhost:8484/v1/actions \
-H "Authorization: Bearer im_..." \
-H "Content-Type: application/json" \
-d '{
"kind": "reddit.comment",
"title": "Reply to: Why is resume advice so conflicting?",
"preview": {
"format": "markdown",
"body": "The advice conflicts because..."
},
"target_url": "https://reddit.com/r/jobs/comments/...",
"expires_in": 86400,
"editable": ["preview.body"]
}'
```
## MCP server (Claude Code / agents)
```bash
npx @impri/mcp
# env: IMPRI_API_KEY=im_... IMPRI_BASE_URL=http://localhost:8484
```
## Project structure
```
server/ TypeScript + Fastify + SQLite — REST API (port 8484)
mcp/ MCP server (stdio) — thin wrapper over the REST API
ui/ Vue 3 + Vuetify — web inbox (port 5173 dev / 8080 Docker)
docker/ Dockerfiles (server.Dockerfile)
docs/ Research, ADRs
```
## CLI
The `impri` CLI lets humans manage the inbox from a terminal — approve, reject, tail pending actions, add watchers, and manage keys — without writing any code.
```bash
# Build and install (local, pre-npm)
cd sdk/typescript && npm install && npm run build
cd ../cli && npm install && npm run build
npm install -g ./cli
# Connect to your instance
impri init --cloud --signup # or: impri init (self-hosted)
# Common commands
impri inbox # pending actions
impri tail # live-tail new actions
impri approve act_abc123
impri watch add github-releases --param owner=fastify --param repo=fastify
```
- [CLI reference](docs/cli.md)
## SDKs & integrations
> v0.1, pre-release. Self-host is the complete path; the hosted cloud is early beta.
| Package | Location | Language |
|---------|----------|----------|
| CLI | `cli/` | Node 18+ |
| Python SDK | `sdk/python/` | Python 3.10+ |
| TypeScript SDK | `sdk/typescript/` | Node 18+ (native fetch) |
| MCP server | `mcp/` / `npx @impri/mcp` | Any MCP client |
```bash
pip install -e sdk/python # Python SDK (local, pre-PyPI)
npm install ./sdk/typescript # TS SDK (local, pre-npm)
npx @impri/mcp # MCP server (published)
```
- [Python SDK reference](docs/sdk-python.md)
- [TypeScript SDK reference](docs/sdk-typescript.md)
- [Integrations](docs/integrations.md) — LangChain, OpenAI Agents, CrewAI, n8n, Make, Zapier, webhook receivers
- [Cookbook](docs/cookbook.md) — recipes for email approval, SQL gating, social posts, idempotent batches, webhook verification, key rotation
## Documentation
- **Web docs:** <https://impri.dev/docs>
- [CLI reference](docs/cli.md) — install, `impri init`, every command with examples, config + env precedence
- [Quickstart](docs/quickstart.md) — signup → first approved action in < 5 min
- [Example agent](examples/approval-gated-agent.mjs) — a complete, dependency-free
agent that proposes an action, waits for approval, then acts and reports back
- [How to add human approval to an AI agent](docs/how-to-add-human-approval-to-an-ai-agent.md)
- [Self-hosting](docs/self-hosting.md) — Docker, env vars, backups, reverse proxy
- [Webhooks](docs/webhooks.md) — HMAC verification, retries, polling fallback
- [Inbox UX & Bulk API](docs/inbox.md) — keyboard shortcuts, bulk approve/reject, search/filter parameters, `POST /v1/actions/bulk-decision` reference
- [Watcher presets](docs/watcher-presets.md) — 18 ready-to-use templates (HN, Reddit, GitHub, npm, arXiv, …); REST + SDK + MCP usage
- [Notification channels](docs/notifications.md) — Slack, Discord, Telegram, ntfy, email, and generic webhook; digest window, auto-disable, SSRF protection
- [Telegram Approval Bot](docs/telegram-approval.md) — in-chat Approve / Reject buttons; setup, security model, troubleshooting
- [Audit log](docs/audit-log.md) — event types, query API (`GET /v1/audit`), export (NDJSON/CSV), retention, and security model
- [`llms.txt`](docs/llms.txt) — machine-readable index for AI assistants
> **Hosted cloud (beta):** a managed instance runs at `app.impri.dev` /
> `api.impri.dev`. Self-serve signup is open: create a project + admin key with
> the **Create an API key** button at [app.impri.dev](https://app.impri.dev), or
> `POST /v1/signup`. It's early beta, so self-host is still the most complete path.
## Self-hosting notes
- SQLite data is persisted in a Docker volume (`impri-data`).
- Set `WEBHOOK_SECRET` env var to a random string for HMAC webhook signing.
- `BASE_URL` should match the public URL of your deployment (used in inbox_url links).
## License
MIT — see [LICENSE](LICENSE). Self-host the full core freely; the hosted cloud
and team features are the paid offering (see `MONETIZATION.md`).
