Kivel

The internet toolkit for AI coding agents: HTTP and webhooks, email, mock APIs and OAuth, files, monitors, memory, authenticators, a password vault, scheduled jobs and status pages, test data and media, developer utilities, DNS and network checks. One MCP connection, with HTTP, a TypeScript SDK, CLI and optional SSH gateway. Use search_tools to discover the complete catalog, describe_tool for inputs and run_tool for utilities. Hosted resources have dedicated tools and lifecycle routes. The catalog drives tool counts and availability; browser utilities stay free. Next.js, Radix UI, Motion, Fastify and PostgreSQL.

Development

Requires Node.js 22+ and pnpm 10.

pnpm install
pnpm dev

Open the site at http://localhost:3001 and create a local account at http://127.0.0.1:3002/signup/. Use the exact workspace address for sign in so the browser sends its session cookie. pnpm dev starts a loopback backend and a PostgreSQL instance with data in .data/. Set DATABASE_URL to use another development database. If a port is occupied, set KIVEL_BACKEND_PORT, KIVEL_SITE_PORT, or KIVEL_APP_PORT before running pnpm dev.

pnpm check

Runs type checks, catalog and API tests, PostgreSQL integration tests, and production builds.

Audio/video tools need ffmpeg and ffprobe on PATH for local development. The Docker image includes both. They accept files up to 10 MiB and 120 seconds, produce at most 5 MiB, and cancel after 20 seconds. Uploads and results are removed after processing; no media history is retained.

Related MCP server: agentforge

Production

Kivel runs on one VPS behind Cloudflare. Every push to main that passes CI runs the Deploy workflow: it builds the app, database and proxy images, pushes them to the private Docker Hub repository tangobee/socket, then runs deploy/server-deploy.sh on the server over SSH. That script backs up the database, pulls the release, waits for it to become healthy and rolls back if it does not; the workflow then runs scripts/production-check.mjs against the live site. Run the workflow by hand to redeploy any commit. It needs the DOCKERHUB_TOKEN, DEPLOY_SSH_KEY and DEPLOY_KNOWN_HOSTS secrets and the DEPLOY_HOST variable.

BILLING_ENABLED=false is the default for self-hosting; Pro/Team checkout stays closed even if Dodo credentials are present. Public production startup requires recovery email configuration. Support is support@kivel.io.

Docker

node scripts/setup-env.mjs
docker compose up -d --build --wait
pnpm test:smoke

Open the public site at http://localhost:8080 and the workspace at http://127.0.0.1:8080. The workspace manages resources, keys and usage. The public site has pricing, docs and the tool catalog. Passwords are generated in ignored .env with owner-only permissions. PostgreSQL uses a persistent volume; the app runs as a non-root user with a read-only filesystem. Do not remove volumes when upgrading.

For public HTTPS, point your domain and its app subdomain at the server. Set up both DNS records before deploying the host split, allow ports 80 and 443, and set DOMAIN in .env. Caddy serves both hosts from one app image and provisions their certificates. Deploy the host split before enabling live events so the previous release can also start on database schema 20.

docker compose -f compose.yaml -f compose.production.yaml up -d --build --wait

The app trusts only the proxy's configured IP. The proxy network uses 10.203.0.0/24; set PROXY_NETWORK_PREFIX to another unused prefix if that range conflicts with your host. HTTP and SSH app ports bind to localhost; only the proxy exposes public ports by default. If you add a CDN or another proxy, configure its trusted IP ranges in Caddy too.

Operations

/health checks the process; /ready also checks PostgreSQL. Logs rotate and exclude payloads, query strings, and tokens. Migrations run transactionally at startup. Keep .env with the persistent volume; changing passwords there does not rotate existing database credentials.

docker compose exec -T database pg_dump -U socket_admin -d socket -Fc > backup.dump

Protect backups and define a short retention period: they include captured data. Restore while the app is stopped:

docker compose stop app
docker compose exec -T database pg_restore -U socket_admin -d socket --clean --if-exists --exit-on-error < backup.dump
docker compose up -d --wait

node scripts/verify-backup.mjs verifies a backup in an isolated temporary database. pnpm scan:images checks all three built images for high/critical vulnerabilities. pnpm test:https tests the built stack with verified local TLS and proxy trust. See backend/README.md for API details. Start at /docs/; the interactive Scalar reference is at /docs/reference/. Tool guides, /blog/, and /compare/ are statically rendered with canonical metadata and sitemap coverage. Unavailable tools remain Coming soon and are excluded from search indexing. Set SITE_URL at build time for custom SEO canonicals; the HTTPS Compose stack uses DOMAIN automatically.

MCP Registry

Kivel is listed on the official MCP Registry as io.kivel/kivel, from server.json. The io.kivel namespace is verified by a DNS TXT record on kivel.io, signed with an Ed25519 key kept outside the repository. To publish a new version, bump version in server.json to match the server's reported version, then:

mcp-publisher validate server.json
mcp-publisher login dns --domain kivel.io --private-key "<hex private key>"
mcp-publisher publish server.json

Clients and billing

pnpm build:packages builds the shared engine, TypeScript SDK, and CLI. SDK and CLI are published on npm: npm install @kivel.io/sdk and npm install --global @kivel.io/cli (then kivel --help). Run pnpm test:packages to verify standalone installable tarballs in release/. See client releases for publishing and installation. Start with /docs/agent-workflows/ for device login, email, memory, monitors and human questions. Use pnpm cli --help; set KIVEL_URL and KIVEL_API_KEY for scripts. For file utilities, pipe bytes to run <id> --file <name>. PDF merging and image-to-PDF accept an ordered file array in SDK/HTTP execution; MCP uses the files argument. The CLI exposes the same multi-file request through api POST /api/tools/<id>/run. The optional SSH gateway listens on localhost:2222 in Docker and accepts API keys as the password for user socket. Its host key persists in ssh_host_keys; verify the fingerprint printed at startup. Set SSH_PORT=0 to disable it. It exposes tool commands, with no shell, forwarding, SCP, or SFTP.

Dodo Payments checkout requires BILLING_ENABLED=true and the four DODO_* credentials/product settings in .env.example to be configured. Rebuild after changing the billing flag so static pricing and runtime checkout agree. DODO_PAYMENTS_ENVIRONMENT defaults to test_mode; enable live_mode only after a complete sandbox checkout and renewal. Use two distinct fixed recurring products with no trials, discounts or usage meters. Set the subscription duration to 20 years, as required by this integration, with a monthly payment frequency. Annual billing is not offered. Prices come from Dodo. Register https://<your domain>/billing/webhook (for production, exactly https://kivel.io/billing/webhook) for subscription lifecycle events. Dodo does not follow redirects, so an old domain or http:// URL fails every delivery with 308; node scripts/production-check.mjs checks the endpoint answers directly. Use the endpoint’s Standard Webhooks signing secret. Entitlements follow verified events and a fresh subscription retrieval, never the checkout return URL. The customer portal is available to workspace owners. When replacing a Dodo product, add its old ID to DODO_LEGACY_PRODUCT_IDS, for example {"pdt_oldpro":"pro"}. Existing subscriptions keep their paid access and new checkout uses the current product IDs.

The deploy workflow builds with the legacy pricing schedule by default. To launch early pricing, create fixed USD monthly products for Pro ($5) and Team ($29) in Dodo. Configure their IDs on the server and map the retired IDs with DODO_LEGACY_PRODUCT_IDS. Set the GitHub repository variable BILLING_PRICE_SCHEDULE to early and deploy. The image uses the same schedule for the public pages and checkout. Checkout checks the Dodo product prices before creating a session. Test the matching products in Dodo test mode before switching live. To move to the $9 Pro price, use standard and add the $5 product ID to the retired map. When rolling back pricing, restore the matching current product IDs with the earlier image.

Account recovery

Set SMTP_HOST, SMTP_PORT (587 by default), SMTP_FROM (an email address), and SMTP_USER / SMTP_PASSWORD for your transactional email provider. Remote SMTP requires TLS; credentials and sender settings stay in .env. Keep AUTH_SECRET stable: it encrypts pending recovery mail. Delivery retries use the PostgreSQL outbox. Configure SMTP before enabling Dodo Payments subscriptions.

Signup always requires and saves an email address, including before SMTP is configured. Users verify that address from Account security. Password recovery uses an eight-digit, single-use code entered on the site, never in a URL. Codes last 15 minutes with five attempts. Resetting revokes all sessions and API keys while preserving workspace resources. Checkout requires a verified recovery email.

Sharing and isolation

Resource pages default to private access. Public links work without a credential; private downloads, mock calls, MCP calls, and webhook senders require a separate sharing token (X-Access-Token or Bearer). Management/inspection tokens control configuration and history; they cannot download private content. Account-owned management requires current workspace access. Rotate a sharing token to invalidate previously issued access tokens. All interfaces default to private; send ?visibility=public explicitly for public sharing. File links contain only the resource ID. Share private access tokens separately; recipients enter them on the receiver page, which sends them in a request header. URL fragments do not authorize access.

Formatters, generators and image/PDF operations run in bounded worker threads. Network tools contact public targets with address pinning, redirect validation and a ten-second deadline (API scenarios allow up to six sequential requests and twenty seconds overall). Execution inputs and results are not retained; mock/MCP configuration never executes user code. Uploads are served as attachments, and previews run locally. Global PostgreSQL allocation caps can be set with MAX_RESOURCE_BYTES, MAX_RESOURCES, MAX_TOTAL_INBOX_BYTES, and MAX_INBOXES, separately from plan limits.

Set maxDownloads=1 for a one-time file link. Its final allowed download removes the stored file contents and releases their storage; metadata remains manageable until deletion or expiry. The web catalog includes one-time and private-sharing pages. SDK and CLI uploads default to private access, and raw API creation uses the same private default.

Original music assets

The built-in CC0 tracks include full MP3 arrangements and editable WAV loops. Source recipes live in packages/tools/src/audio.ts; reproduce the MP3 files with pnpm build:packages followed by node scripts/build-music-library.mjs (FFmpeg required). Track-specific license notes ship in frontend/public/music/LICENSE.txt. The composer and image tools also publish option metadata through GET /api/tools/:id, kivel describe <id>, and MCP describe_tool.

API test scenarios use the same hosted execution endpoint and clients. The workbench supports variables, separate secret inputs, response checks and JSON captures; exports exclude secret values. See /docs/api-scenarios/ for the format and report contract.

Stateful CRUD mocks add one seeded collection to the existing mock lifecycle. Record reads and writes use /mock/:id/:collection; management reset is POST /api/mocks/:id/reset. SDK/CLI/SSH accept /mock/ paths with a separate caller token; MCP exposes call_mock_api. See /docs/stateful-crud-mocks/ for formats, revision guards, limits and the distinction between seed and live exports.

HTTP echo endpoints use the same mock lifecycle with {name, routes: [], echo: true}. Call /mock/:id with an optional relative path to inspect redacted request metadata and a parsed JSON/text body. Requests are not retained. See /docs/http-echo/.

Test agent payments

Test mode wallets, x402 v1 paywalls and hosted checkouts use fake units only. There are no real funds, blockchain transactions or private keys. Wallet limits and approval thresholds require an owner/admin browser session; agent keys cannot change them. Above the threshold, agents share the approval URL and resume with the same idempotency key after a human answers. Hosted checkouts collect no card details. Checkout webhooks are signed and retried using the existing forwarder.

Use create_test_wallet, wallet_pay and list_wallet_transactions over MCP, the SDK test payment methods or kivel test-wallet, test-paywall and test-checkout. All three use existing resource/storage quotas and mock retention. Keep AUTH_SECRET stable for encrypted webhook secrets and payment tokens. Guide: Test an agent that pays.