# 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

Two ways to run Impri — pick one. Both give you an API key and an inbox URL in under 5 minutes.

### Cloud (no install)

```bash
curl -s -X POST https://api.impri.dev/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'
# → { "key": "im_...", "project_id": "proj_...", ... }
```

Or skip curl and click **Create an API key** at [app.impri.dev](https://app.impri.dev) — same result. Your inbox is at **app.impri.dev**, the API base URL is `https://api.impri.dev/v1`. It's early beta but is the fastest way to try Impri with no Docker required.

### Docker Compose (self-host, < 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, self-host)

**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: `https://api.impri.dev/v1` (cloud) or `http://localhost:8484/v1` (self-host)  
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 https://api.impri.dev/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"]
  }'
```

Self-hosting instead? Swap the URL for `http://localhost:8484/v1/actions`.

## MCP server (Claude Code / agents)

```bash
npx @impri/mcp
# cloud:      IMPRI_API_KEY=im_...  IMPRI_BASE_URL=https://api.impri.dev
# self-host:  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 — both cloud and self-host work today; expect rough edges either way.

| 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

## 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`).