Skip to content
AgereePublic

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

2,127 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

OpenInstinct

A personal iMessage assistant for your accounts and your context.

It can research, read your mail and calendar, and run scheduled work for you. You stay in control of your passwords, credit cards and context. Browser execution is not included in this build.

It's Open Source, self-hostable, and can use any model. One-click deploy to Vercel and get rolling.

Deploy with Vercel

OpenInstinct booking movie tickets over iMessage — it walks Fandango to checkout and reports the theater, showtime, seat, and total

Agents: For the simplest deployment, give your human the Deploy with Vercel link above and have them complete the guided flow. It automatically provisions and connects Postgres and Vercel AI Gateway access; then have them set the installation secrets and file storage below and complete the Photon iMessage setup.

Why self-host?

Personal agents are much more useful when they can sign in, book, buy and act on your behalf. But your accounts, your passwords, are the keys to your digital kingdom. OpenInstinct runs in your own Vercel account. Secrets are encrypted before they touch your database and models never see them. Verify yourself by reading the code!

Deployment

The deploy button provisions Neon for Postgres. Images and files live in a private S3 bucket of Object Storage on Cloud.ru. iMessage runs on a Photon project you create separately. Vercel AI Gateway handles inference. Usage is billed to your Vercel account. Browser execution is not included in this build, so the agent works through its connected services, public search, and page fetches only.

Set the Better Auth and vault-encryption keys once and never change them: a new session secret signs everyone out, and a new encryption key leaves the vault unreadable. Outside Vercel, set the public application URL as well:

BETTER_AUTH_SECRET="$(openssl rand -base64 32)"
BETTER_AUTH_URL=https://your-host
SECRET_ENCRYPTION_KEY="$(openssl rand -base64 32)"

The application database schema and versioned migrations live in db/. The Drizzle application store uses DATABASE_URL for runtime queries; its migration commands require the direct DATABASE_URL_UNPOOLED connection. Run pnpm db:migrate before starting against a new or upgraded local database. Vercel uses Turbo to run the uncached migration task before its application build. See db/README.md for existing-database adoption, environment loading, and constraint-validation sequencing. Better Auth retains its separate migration path. Importing an existing Convex deployment is covered by docs/migrate-from-convex.md.

Treat SECRET_ENCRYPTION_KEY as production key material: losing it loses the vault, and rotating it requires re-encrypting existing vault values.

AgentMail: the agent's own email

Set AGENTMAIL_API_KEY on the server and AGENTMAIL_WORKSPACES to a comma-separated list of workspace IDs to narrow it. Unset, empty or * means every agent once the key is set; off switches AgentMail off for all. Every workspace agent receives one persistent inbox when its workspace is created or next accessed; existing agents are provisioned the same way. Chats and temporary task subagents share the workspace identity and do not allocate extra inboxes.

AGENTMAIL_PROXY_URL optionally routes only these API requests through an authenticated HTTP(S) CONNECT proxy. Use it when the provider refuses the server's direct egress; HTTPS certificate verification remains enabled.

Bro can show its address and list, read, and send mail using agent-mail-* tools. These operate only on its workspace's own inbox. Sending requires an explicit user request and follows the existing outbound-message rules; incoming mail never authorizes actions. This integration does not start turns automatically when mail arrives. The user's Gmail remains a separate service.

The Free plan currently includes 3 inboxes and 3,000 emails/month (100/day). Provider quota or downtime leaves the agent usable; inbox provisioning retries on its next access with the same client_id. Repeated sends use AgentMail's idempotency header and a persistent receipt; an interrupted send older than 23 hours is refused because the provider expires its send key after 24 hours.

For an existing production agent, run python scripts/cloudru-app-host/host.py ops bro-app-1 agent-mail.sh provision WORKSPACE_ID. The self-test action sends one message to that agent's own address and checks real send, replay, list, and read. It does not contact the owner's Gmail.

File storage

Images and file attachments live in a private bucket of Object Storage on Cloud.ru, under artifacts/. Set BROWSER_STATE_BUCKET, CLOUDRU_S3_TENANT_ID, CLOUDRU_KEY_ID and CLOUDRU_KEY_SECRET; without them nothing is stored and pictures are not offered.

Profile facts are stored as revisioned database records, and the old memory file a scope imports once lives in the memory_documents table. See the memory architecture for the authority, semantic-index, deletion, and rollout contracts.

Ongoing undertakings use a separate workstreams memory slot backed by the application database. Run the application migrations before using this feature; it needs no additional service or credentials. The root agent can save goals, constraints, decisions, source-linked observations, and unresolved steps across conversations. It recalls an index of the eight most recently updated active or waiting workstreams, then reads the selected record before continuing. Older and completed workstreams remain searchable.

Workstreams are scoped by authenticated workspace and Eve's deployment-aware memory key. Updates require the current revision. Each scope retains content for up to 100 bounded records; the agent asks which obsolete record to forget at capacity. Forgetting erases the content and source references, retaining only a tombstone to prevent an interrupted save from restoring them. Existing chat history is unchanged. This slot is available only in interactive root turns; remembering work does not start a job, create a schedule, or authorize an action.

Photon iMessage setup

iMessage uses portable Photon project credentials, so it works on Vercel and on any other host. After the first deployment:

  1. Create a Photon project and register its iMessage line.
  2. Register a Photon webhook for https://<your-host>/eve/v1/photon and copy its signing secret.
  3. Set the three variables in the host's encrypted environment:
vercel env add IMESSAGE_PROJECT_ID production
vercel env add IMESSAGE_PROJECT_SECRET production
vercel env add IMESSAGE_WEBHOOK_SECRET production
vercel deploy --prod

Repeat the variables for preview or development if those environments should send and receive iMessage too. IMESSAGE_PHONE_NUMBER is an optional E.164 override that adds a click-to-message shortcut in the workspace and on the sign-in screen; delivery itself uses the project's registered line.

No separate per-user verification step is required. A sign-in code is sent to the phone number entered on the sign-in screen, and a first message from an unknown number creates that user's account, because Photon delivering the message already proves possession of the number.

Browser Use Cloud

browser_task runs a website errand — sign in, fill the form, finish the checkout — in a hosted Browser Use cloud browser. The tool, and the instructions that describe it, appear only when BROWSER_USE_API_KEY is set; without it the agent says plainly that it cannot operate a website.

  1. Create a Browser Use Cloud project and copy its API key.
  2. Register a webhook for https://<your-host>/eve/v1/browser-use in the Browser Use dashboard (Settings → Webhooks) and copy its signing secret. Optional: Browser Use sends webhooks for V2 tasks and V3 sessions only, and the errands run on the V4 API. Completion is found by the poller, which checks open runs every few seconds while any are running.
  3. Set the variables in the host's encrypted environment:
vercel env add BROWSER_USE_API_KEY production
vercel env add BROWSER_USE_WEBHOOK_SECRET production
vercel deploy --prod

BROWSER_USE_MAX_COST_USD is the ceiling every run is created with and defaults to 1: Browser Use stops a run that reaches it, so a task that loops or wanders into an expensive site cannot keep spending unattended. Raise it for errands that genuinely need longer sessions.

BROWSER_USE_PROXY_COUNTRY is the ISO 3166-1 alpha-2 residential-proxy country every run browses through and defaults to ru. BROWSER_USE_MODEL overrides the hosted agent the cloud runs; leaving it unset uses the v4 API's documented default. BROWSER_USE_BASE_URL overrides the API origin and exists so a staging deployment can point at a stand-in.

Each workspace keeps one persistent Browser Use profile, so a site stays signed in between errands. Saved vault logins are bound to the exact origin they were saved for, and the saved card is bound only when the user approved paying on that errand; the values are typed by Browser Use and are never visible to any model in this system.

A one-time code sent as a follow-up is typed straight into the page the run is on, over the Chrome DevTools Protocol, before the hosted agent is asked to do anything with it. The agent could type it — this is a shortcut, not a repair — but a queued message waits for its next step, and a code that arrives after the run has finished costs a whole new run before anyone touches the keyboard. Bank codes expire in a couple of minutes, so that gap is the difference between a payment that goes through and one the person starts over.

The search covers embedded frames, which is the whole point: a bank's 3-D Secure challenge is a cross-origin iframe, and the page's own document does not contain its field. Every frame is scored before anything is typed anywhere and only the best one is filled, so a page carrying a bank frame and three ad frames cannot get the code sprayed across all four; the page's own document keeps a tie, an embedded frame needs a naming signal rather than merely a focused input, and a frame too small to hold a form is skipped whatever its input is named. A password field is never filled and a pay or order button is never pressed. Whatever the entry does, the person's message still reaches the hosted agent, which is told what is already in the page so it does not type the code a second time; when no field can be identified with confidence, nothing is typed and the agent handles the code exactly as it did before.

npm run cdp:probe checks that against a real Chromium, with the code field inside a cross-site frame and an ad frame, a 0x0 tracking frame, a password field and a pay button around it. npm run cdp:probe:cloud runs the same walk against a real Browser Use browser through the production path, to catch the vendor fronting the protocol in a way a flattened auto-attach cannot survive; it costs about a cent and always stops the browser afterwards. Neither is part of pnpm check, which stays offline.

Telegram setup

Telegram is a second conversation channel for an account that already exists. A person links their Telegram once, and afterwards messages from that Telegram account run as the same user, workspace, memory, vault, and schedules.

  1. Create a bot with @BotFather, then copy its token and its username (the handle without the leading @).
  2. Set the three variables in the host's encrypted environment:
vercel env add TELEGRAM_BOT_TOKEN production
vercel env add TELEGRAM_BOT_USERNAME production
vercel env add TELEGRAM_WEBHOOK_SECRET_TOKEN production
vercel deploy --prod

TELEGRAM_WEBHOOK_SECRET_TOKEN is a secret you choose; Telegram echoes it back in the X-Telegram-Bot-Api-Secret-Token header, and inbound webhooks that do not carry it are rejected.

  1. Point the bot at the deployment's webhook route:
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://<your-host>/eve/v1/telegram",
       "secret_token":"'"$TELEGRAM_WEBHOOK_SECRET_TOKEN"'",
       "allowed_updates":["message","callback_query"]}'

To link an account, open the workspace page and choose Link Telegram, or ask the assistant over iMessage to link Telegram. Either one mints a one-time https://t.me/<bot>?start=link_<token> deep link that expires after 30 minutes. Opening it in Telegram binds that Telegram account to the workspace. One Telegram account maps to exactly one workspace, and one workspace holds at most one Telegram account.

Only private chats reach the agent; group messages are ignored. A message from an unlinked Telegram account gets one short explanation of how to link, at most once an hour per chat.

Inbound photos and voice notes

A photo, an image or PDF document, or a voice note sent over Telegram or iMessage reaches the model as bytes the channel downloaded itself, not as a URL. Photos are served at the largest rendition under 3 MB with the media type read from the file's magic bytes; PDFs up to 10 MB become file parts; other files are described to the model in one line. A message that carries only a picture still tells the model [фото].

Voice notes are transcribed through the direct model provider's audio endpoint (OpenRouter, or RouterAI's /audio/transcriptions, see Model provider), so a deployment without one answers a voice note with one line saying voice is not supported. On RouterAI the ROUTERAI_STT_* variables take the place of the OPENROUTER_STT_* ones below (default openai/whisper-large-v3-turbo, fallback openai/gpt-4o-transcribe). iMessage voice notes arrive as CAF-Opus and are remuxed to Ogg in process. OPENROUTER_STT_MODEL is the transcription model (default qwen/qwen3-asr-flash-2026-02-10), OPENROUTER_STT_FALLBACK_MODEL takes over when the first model rejects the clip (default openai/gpt-4o-transcribe), and OPENROUTER_STT_LANGUAGE is the language hint (default ru; auto lets the model guess). The transcript reaches the model as a line starting with [голосовое]; when nothing could be transcribed and the message has no text, the person is asked to retry and no model turn runs.

When the model provider refuses a turn (out of credits, rate limited, down), Telegram and iMessage answer the person with a short «я прилёг, скоро вернусь» (or its English twin for someone writing in English) instead of silence; any other failed turn gets a short apology. To hear about an empty balance before people do, set OPENROUTER_MANAGEMENT_KEY (the credits endpoint rejects an inference key) and TELEGRAM_OWNER_CHAT_ID. Every ten minutes the schedule reads the OpenRouter balance and, when it falls below OPENROUTER_CREDITS_ALERT_USD (default 5), messages the owner. Alerts go through a separate service bot, OPS_ALERT_BOT_TOKEN in OPS_ALERT_CHAT_ID (the pair the VM watchdog reads); without it, through Bro's own bot into the owner's chat with Bro, under a header saying the message is not Bro's. On RouterAI the ordinary ROUTERAI_API_KEY reads the balance, already in roubles, and the threshold is ROUTERAI_CREDITS_ALERT_RUB (default 300). The alert repeats once a day while the balance stays low, sooner if it keeps halving, and re-arms once the balance recovers; its state lives in operational_alerts.

Pictures, clips and chat games

Unless VIDEO_WORKSPACES is off (or names only some workspaces), a person who asks for a clip gets generate_video: a few seconds with sound from words, or their photo or an earlier picture brought to life, through RouterAI's /videos (ROUTERAI_VIDEO_MODEL, default heygen/heygen-video-1). The clip is kept as a private artifact like a picture and reaches Telegram as a video.

With a direct model provider and the private Object Storage bucket on Cloud.ru (see File storage), the agent gets a generate_image tool that draws through the provider's image API (OpenRouter's /images, RouterAI's /images/generations). The model is OPENROUTER_IMAGE_MODEL (default google/gemini-3.1-flash-lite-image) or ROUTERAI_IMAGE_MODEL (default microsoft/mai-image-2.6-flash) and must accept reference images: the person's photos from the conversation (up to the four newest) and earlier pictures travel as references, so a card can show the person's own dog and "make it brighter" edits the last version instead of starting over. Pictures are stored as private artifacts and reach Telegram and iMessage as real photos through send_message. Without the key or the store the tool is not offered, and the agent says plainly that it cannot draw.

Chat games need no configuration: the agent hosts trivia and other games in the conversation one question per message, reacts to answers, and keeps score.

Landing and onboarding

/ is a public Russian landing page and the signed-in workspace lives at /workspace. The landing asks for nothing: under the film there is one call to action, «Написать бро», an sms: deep link into IMESSAGE_PHONE_NUMBER with «Привет» prefilled, and the number itself underneath for a visitor who is not on an iPhone right now. No account is created here: the first inbound iMessage creates it, so nothing is provisioned before a person actually writes. A deployment without IMESSAGE_PHONE_NUMBER has no line to open and says onboarding is closed instead of linking into nowhere.

The film and the og image are served from /brand, which the auth proxy must not touch: its matcher excludes those paths, because a static asset redirected to /sign-in is an asset that silently disappears from the page.

scripts/lib/migrate-from-convex.ts still registers a Photon shared user per migrated phone and stores it in the onboarding_requests table, which replays the number a phone already has instead of buying a second Photon user.

/oferta carries the Russian public offer the landing links to.

Оплата и лимиты

Доступ платный помесячно через YooKassa. YOOKASSA_SHOP_ID и YOOKASSA_SECRET_KEY вместе включают оплату; без любого из них деплой работает в бесплатном режиме — лимиты те же, ссылки на оплату нет. PRICE_RUB (по умолчанию 2000) — цена месяца.

GET /api/pay создаёт платёж для кабинета вошедшего пользователя и перекидывает браузер на подтверждение YooKassa; return_url ведёт на /workspace?paid=1. POST /api/yookassa — публичный вебхук: из тела он берёт только идентификатор платежа, перезапрашивает платёж у YooKassa и только после этого продлевает доступ на 30 дней от максимума из «сейчас» и текущей даты окончания. Продление идемпотентно по идентификатору платежа. В кабинете строка «Подписка» показывает состояние и ссылку на оплату.

USAGE_LIMITS включает или выключает лимиты целиком; по умолчанию off — закрытая бета идёт без лимитов по решению владельца, и оплата в чате не предлагается. При USAGE_LIMITS=on лимиты считаются по рабочему пространству: сообщения — за местный день, браузерные поручения и нарисованные картинки — за местный месяц. FREE_MESSAGES_PER_DAY (30), PAID_MESSAGES_PER_DAY (500), FREE_BROWSER_RUNS_PER_MONTH (5), PAID_BROWSER_RUNS_PER_MONTH (60), FREE_IMAGE_GENERATIONS_PER_MONTH (10), PAID_IMAGE_GENERATIONS_PER_MONTH (100). Местный день и месяц берутся из таймзоны в Personal Info, по умолчанию Europe/Moscow. За лимитом сообщений человек один раз в день получает сообщение о лимите со ссылкой на оплату, остальные сообщения тихо отбрасываются; за лимитом поручений browser_task не запускается, а за лимитом картинок generate_image не рисует, и оба возвращают модели объяснение.

Connected apps (Google, Notion, Slack and more)

People connect their own accounts through Composio: Composio stores and refreshes the grants, and Bro calls the apps through Composio's proxy and tools with the person's connected account id, so no provider token ever reaches Bro. The Composio user_id is the Bro user id. Without COMPOSIO_API_KEY the integrations are absent.

  1. Create a Composio project and a project API key; set COMPOSIO_API_KEY.
  2. Create Composio-managed OAuth auth configs and set their ids:
    • googlesuper for Gmail, Calendar, Drive, Contacts, Sheets and Docs in one consent → COMPOSIO_GOOGLE_AUTH_CONFIG_ID, and optionally a second one for the read-only level → COMPOSIO_GOOGLE_READ_ONLY_AUTH_CONFIG_ID (without it read-only reuses the full one and Bro refuses writes itself);
    • notion → COMPOSIO_NOTION_AUTH_CONFIG_ID;
    • slack with user-token scopes → COMPOSIO_SLACK_AUTH_CONFIG_ID. Scopes (credentials.scopes of the managed config): full Google — userinfo.email, userinfo.profile, https://mail.google.com/, calendar, contacts.readonly, drive, spreadsheets, documents; read-only Google — the same without spreadsheets and documents; Slack — channels:history,channels:read,chat:write,groups:history,groups:read,im:history,im:read,im:write,mpim:history,mpim:read,search:read,users:read,users:read.email (Composio sends them as user_scope); Notion takes none. Other apps reached through the apps tool get a managed auth config on first connect.
  3. People connect from the chat (a sign-in card, connect_google, connect_app) or from /workspace; disconnecting revokes and deletes the Composio connected account.

Gotchas:

  • Composio's managed Google app is approved for broad scopes only; narrower read-only scopes outside its approved set can be blocked by Google. A truly narrow read-only grant needs your own Google OAuth client in its own auth config.
  • Sending email, creating calendar events, adding Notion tasks, posting to Slack and every write through apps always require approval. Calendar events with attendees send Google invitations.
  • Google Contacts search uses a provider-side lazy cache, so a contact created moments ago may not appear immediately.

Personal Mail.ru and Yandex mail

These integrations use the providers' OAuth directly, then IMAP and SMTP over TLS. They do not use Composio. Set MAILRU_MAIL_CLIENT_ID, MAILRU_MAIL_CLIENT_SECRET, YANDEX_MAIL_CLIENT_ID, and YANDEX_MAIL_CLIENT_SECRET for the providers you offer. Enable the pilot with MAIL_WORKSPACES containing workspace ids (or * for all workspaces).

Register each exact callback on the application's public origin: /api/personal-mail/mailru/callback and /api/personal-mail/yandex/callback. Mail.ru needs openid email mail.imap offline_access; its endpoints are resolved through OpenID discovery. Yandex needs login:email, mail:imap_ro for read-only, and mail:imap_full mail:smtp for full access. These permissions must be enabled in the provider application, not merely passed in an authorization URL. Yandex also requires IMAP and OAuth access enabled in mailbox settings.

People connect from /workspace or connect_mail. OAuth state is short-lived, single-use and bound to the signed-in workspace; both providers use PKCE. Tokens and PKCE verifiers are encrypted with the installation encryption key and never returned to the agent. Connection completion checks actual IMAP access and, for full access, SMTP authentication without sending a message.

The mail-* tools search and read messages without marking them read, save plain-text drafts, send plain-text messages, and make reversible flag/move changes. Read-only blocks every write; Mail.ru's broader IMAP permission is restricted locally by Bro. Attachments are metadata only. SMTP sends have durable replay protection; an uncertain delivery is never automatically sent again. Disconnecting deletes the local tokens, not the mailbox or the provider's consent; revoke that consent in the provider's account settings.

YooMoney wallet

Bro reads a person's YooMoney wallet — the balance and the operation history — and pays from its balance through the wallet API, with the person's OAuth consent: transfers to other wallets and the services of YooMoney's catalogue (mobile top-ups, internet, utilities). Every payment waits for the person's yes to a question with its exact total. Register an app at https://yoomoney.ru/myservices/new with the Redirect URI <origin>/api/yoomoney/callback and "verify authenticity" (client_secret) on, then set YOOMONEY_CLIENT_ID, YOOMONEY_CLIENT_SECRET and the pilot YOOMONEY_WORKSPACES (workspace ids or *). The wallet API has no test mode: request-payment checks a payment without charging it. The first time a payment needs the wallet, Bro sends a link (in Telegram, a button that opens it as a Mini App) to /yoomoney/<id>: three steps on one page — sign in to YooMoney or open a wallet there, allow Bro to pay, link a card — and once the person is through, Bro carries on in the chat by itself, up to the question with the payment's total. The page acts only for a device that proved it is the person's (the cabinet's session, or Telegram's signed launch data of the chat's user), and YooMoney's callback checks that device too. Bro asks for account-info operation-history payment-p2p.limit(1,50000) payment-shop.limit(1,50000) money-source("wallet","card"). A service the balance cannot cover, or one YooMoney takes from a card only, is paid from the wallet's linked card; when YooMoney wants its CVV, on a page Bro links to. A minute's tick reads back the payments in flight nobody asks about (a card payment whose person never came back from the bank, an answer that was lost) and tells the chat how each one went. Without the .limit() YooMoney's default is 3,000 ₽ a day; Bro asks for 50,000 ₽, which the person can change on the consent page. A payment refused for the limit gets a link to consent anew (the tool's reconnect): the current access stays until the new one is granted.

Local development

The Deploy with Vercel flow above is the simplest way to run OpenInstinct. It provisions the required services and credentials automatically. Local development is a manual path and requires:

  • Node.js 24 and pnpm 11.24.0
  • Docker Desktop or another running Docker Compose installation
  • AI Gateway access from an API key or a linked Vercel project's OIDC token

First clone and install the application:

git clone https://github.com/Merit-Systems/OpenInstinct.git
cd OpenInstinct
pnpm install --frozen-lockfile

Model provider

Inference runs through the Vercel AI Gateway by default, which bills your Vercel account and refuses most models on the free tier — a Gateway deployment needs paid credits. Set OPENROUTER_API_KEY to route every turn through OpenRouter instead. OpenRouter then owns model selection: OPENROUTER_MODEL is the default id for a workspace that has not chosen one, OPENROUTER_MODEL_CONTEXT_TOKENS declares the context window, OPENROUTER_PROVIDER_ORDER pins upstream hosts, and OPENROUTER_REASONING_EFFORT turns the thinking phase on at low, medium, or high. OPENROUTER_MAX_OUTPUT_TOKENS caps what one step may write, reasoning included (16,384 by default, 32,768 with reasoning on): OpenRouter reserves credit for that many tokens before it answers, and without a cap it reserves the model's whole limit. The workspace page switches its model picker to an OpenRouter id field whenever the key is present.

RouterAI serves the same API from Russia and is chosen with MODEL_PROVIDER=routerai plus ROUTERAI_API_KEY (MODEL_PROVIDER=openrouter forces OpenRouter; left unset, the OpenRouter key decides as above). Its settings mirror OpenRouter's under the ROUTERAI_ prefix: ROUTERAI_MODEL (default deepseek/deepseek-v4.1-flash), ROUTERAI_MODEL_CONTEXT_TOKENS, ROUTERAI_REASONING_EFFORT, ROUTERAI_MAX_OUTPUT_TOKENS, ROUTERAI_SEARCH_MODEL and ROUTERAI_SEARCH_MAX_RESULTS (default 5), and ROUTERAI_BASE_URL (https only). ROUTERAI_PROVIDER_ORDER pins upstream hosts (for deepseek/* the default is deepinfra, which keeps the prompt cache; a pinned host that fails an answer is skipped for ten minutes) and ROUTERAI_PROVIDER_IGNORE skips hosts for every model. RouterAI's own DeepSeek endpoint hangs, so deepseek/* always skips it. Costs come back in roubles and are recorded as roubles, without a dollar price.

With CLOUDRU_FM_API_KEY (a Cloud.ru Foundation Models API key) a RouterAI chat call whose route fails — a network error, a silent connection, or a 500/502/503/504 — is answered by CLOUDRU_FM_MODEL (default deepseek-ai/DeepSeek-V4.1-Flash) at CLOUDRU_FM_BASE_URL, and chat calls skip RouterAI for five minutes before one call tries it again. Web search does not fall back, and those steps are recorded with their tokens but unpriced.

web_search changes shape with the provider. The framework tool is provider-managed: an AI Gateway model searches through Exa, and a direct provider model is handed that provider's own search tool. OpenRouter exposes neither, and neither does RouterAI, so with either one the agent swaps in its own ordinary function tool, which runs the query through the provider's web plugin on Exa, falls back to Perplexity on a timeout, a throttle, a gateway failure or an empty answer, and returns up to eight titles, URLs, and page excerpts (on RouterAI up to ROUTERAI_SEARCH_MAX_RESULTS, as each result is billed); sites limits it to given sites. OPENROUTER_SEARCH_MODEL picks the model the plugin hands the results to (nothing it writes is read) and falls back to OPENROUTER_MODEL. The tool keeps the name web_search, and web_fetch is unaffected because it is an ordinary function tool on every provider.

For fully manual setup, copy the environment template and add your AI Gateway key:

cp .env.example .env.local

# Set AI_GATEWAY_API_KEY in .env.local.

If you already use a Vercel project, link it to pull AI Gateway access:

pnpm exec eve link --project <your-vercel-project> --non-interactive

Then start OpenInstinct:

pnpm dev

pnpm dev starts PostgreSQL from compose.yaml, applies the committed database migrations, and starts the application. Stopping the development process also stops and removes the PostgreSQL container; its data remains in the postgres-data volume for the next run. Run pnpm dev:app when intentionally using an externally managed database instead.

Local development otherwise uses the same vault and AI Gateway path as the Vercel deployment. Better Auth and vault encryption use stable local-only defaults when their variables are unset. Vercel deployments provision them automatically in private Blob; other production hosts require explicit secrets.

Warning

This is not software intended for production use.


Built on Vercel · Photon · Neon

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages