Omentir

Omentir is an open-source alternative to LinkedIn outreach and automation tools like HeyReach and Gojiberry.

It's an AI sales workspace for finding qualified LinkedIn prospects, drafting contextual outreach, running human-paced campaigns, and handling replies — but you own the code and run it on your own infrastructure.

Use the managed product at omentir.com, or self-host the same application code with your own Firebase, Gemini, and Unipile accounts.

One codebase: hosted cloud and self-host share this repo. RUN_LOCALLY=TRUE switches auth, billing, marketing, and hosted-only mail off. Public brand contacts for omentir.com stay in source on purpose (see src/lib/hosted-identity.ts); they are not used for self-hosted operation.

Connect from other AI apps (Claude, ChatGPT, Grok, Grok Bot, Cursor, …)

People use Omentir from chat and coding agents without sharing LinkedIn passwords:

1. In Omentir: connect LinkedIn and fill Workspace.
2. Chat apps (Claude, ChatGPT, Grok): Settings → Connectors → add
   https://omentir.com/api/agent/v1/mcp → sign in and approve Connect workspace → enable tools in the chat.
   No API key.
3. Grok Bot (the always-on teammate app, not grok.com chat): Settings → Plugins → search Marketplace for Omentir. If it is not listed, add the same MCP URL as a custom server → approve Connect workspace. Do not sign LinkedIn into the Bot computer. Grok Bot integration.
4. Cursor / Claude Code / scripts: create a key on the API page and send
   Authorization: Bearer <token> to the MCP endpoint or REST /api/agent/v1/*.
5. Ask the assistant to create a classic lead finder or a Steal Customers agent (mode: steal_customers + competitor company URLs). If you have more than one company, ask it to list workspaces and switch.

Docs: MCP integration, Agent API, agents.md (machine guide), OpenAPI.

Self-hosting

Omentir is self-hostable with external managed services. It is not offline or dependency-free. You provide Firebase/Firestore, Unipile, and either a Gemini API key or a Google Cloud Vertex AI project.

Self-hosting removes the Omentir subscription, but Firebase/Google AI and Unipile can still cost money.

Quick start on localhost

Install Git and either Docker with Docker Compose, or Bun 1.3. Then clone and configure the project:

git clone https://github.com/vanshyadav1408/Omentir.git
cd Omentir
cp .env.example .env

Open .env and fill in every uncommented blank value. Complete the provider setup below before starting the server.

Generate independent secrets with:

openssl rand -base64 48

Use that (or a password manager) for at least:

• LOCAL_SESSION_SECRET (required)
• LOCAL_APP_PASSWORD (required unless you explicitly allow open access — see Access control)
• CRON_SECRET (required unless automation is fully disabled)
• UNIPILE_WEBHOOK_SECRET (required for reply and relation webhooks)

For an initial setup with all automation disabled, leave CRON_SECRET blank and set AUTOMATION_DISABLED=true instead. Keep ENABLE_LIVE_AUTOMATION=false until dry-run output has been reviewed.

Run with Docker

Docker is the supported self-hosting path. Omentir runs on amd64 and arm64.

docker compose up --build -d
docker compose logs -f omentir

Open http://localhost:3000. Press Ctrl+C to exit the log view without stopping Omentir. Stop the server later with docker compose down.

Port binding: Compose publishes the app as 127.0.0.1:3000:3000 only. That means the container is reachable from the same machine (http://localhost:3000), not from other devices on your LAN or the public internet. This is intentional: a misconfigured or passwordless instance must not become reachable just because Docker started.

To expose the app on a real host (LAN/VPS):

1. Put HTTPS reverse proxy (Caddy, nginx, Traefik, etc.) on the public interface.
2. Proxy to 127.0.0.1:3000 (or change the Compose bind only if you understand the risk).
3. Set APP_BASE_URL to the exact public HTTPS origin (no trailing slash).
4. Keep a strong LOCAL_APP_PASSWORD (do not enable open access on a public URL).

Run with Bun

For local development:

bun install
bun run dev

For a production-style local server:

bun install
bun run build
bun start

Open http://localhost:3000. Sign in with LOCAL_APP_PASSWORD unless you opted into open access (see below).

Bun is the package manager and script runner, but bun run dev deliberately starts Next on Node rather than under bun --bun. In dev, Turbopack loads every package in serverExternalPackages (firebase-admin among them) through a hashed specifier such as firebase-admin-<hash>/firestore, which only resolves via a loader hook Next installs in Node. Bun's resolver does not run that hook, so bun --bun next dev fails on the first Firestore import with ResolveMessage: Cannot find module. Production is unaffected: built output emits plain requires, so build and start still run under Bun.

Access control (local login)

Self-host mode uses a single workspace and a signed, HTTP-only session cookie (omentir_local_session), not Clerk.

Additional login hardening that matters for operators:

• Origin check: POST /api/local-auth/login only accepts requests whose Origin matches APP_BASE_URL.
• Brute-force throttle: wrong passwords are rate-limited per source IP (in-process).
• Post-login redirects: the ?next= return path is sanitized so values like //evil.com cannot open-redirect the browser after sign-in. Only same-origin relative paths (starting with a single /) are allowed.
• Cookie flags: session cookies are HttpOnly, SameSite=Lax, and Secure when APP_BASE_URL is HTTPS.

1. Provider setup

1. Create a dedicated Firebase project. Enable Firestore and create a service account. Never reuse the hosted Omentir project.
2. Deploy the required indexes with firebase deploy --only firestore:indexes, or create the indexes from Firestore error links. The source is firestore.indexes.json.
   • Also deploy firebase deploy --only firestore:rules. Omentir reaches Firestore only through the server-side Admin SDK, so the shipped firestore.rules denies all direct browser/client access. Keep it deployed — it stops anyone from reading or writing your data with a leaked project ID or web API key.
3. Create a Unipile account and obtain its DSN, API key, and webhook secret. Unipile is paid and LinkedIn can restrict automated accounts.
4. Create a Gemini API key. For Vertex instead, set GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, and GOOGLE_APPLICATION_CREDENTIALS_JSON, enable Vertex AI, and grant the service account Vertex AI User.

2. Configure

Copy .env.example to .env. Required local settings are validated at server startup:

* Treat LOCAL_APP_PASSWORD as a secret even though it is typed by a human.