Setup guide

Set up the agent, start to finish

This guide assumes you have never opened a terminal. It starts at "make a GitHub account" and ends with an agent answering questions in your Slack. Budget about ninety minutes, and less than that if you stop after step 3.

Everything here is free unless you choose otherwise. The one thing that eventually costs money is the AI model usage, which is pay-as-you-go and pennies while you are learning.

01Make three free accounts

You need three things, and all three have a free tier that is genuinely enough to finish this guide.

GitHub — where the code lives

Go to github.com/signup. GitHub is where code is stored and shared. You are going to make your own copy of the agent here, which is what "forking" means.

Vercel — where it runs

Go to vercel.com/signup and choose Continue with GitHub. Signing up through GitHub links the two accounts, which saves you a step later. Vercel is the company that hosts the running agent; their free Hobby plan is fine to start.

Node.js — so your computer can run the code

Download the LTS version from nodejs.org and run the installer. Nothing to configure. This is what lets your own machine run the agent while you experiment, before it goes on the internet.

02Get the code onto your computer

First make your own copy. Open the repository and click Fork in the top right, then Create fork. You now own a full copy at github.com/your-username/oss-moperator.

Now open your terminal and run these four commands, one at a time. Replace your-username with your actual GitHub username.

git clone https://github.com/your-username/oss-moperator.git
cd oss-moperator
npm install
cp .env.example .env.local

In order: download your copy, move into the folder, install the libraries it depends on, and create the file where your private keys will live. The install prints a lot of text — that is normal.

03Try it against a fake CRM first

Before connecting anything real, run it against a pretend Salesforce. Nothing you do here can touch production data, because there is no connection to production data.

MOPERATOR_MOCK=true npm run agent

You now have a chat prompt in your terminal. Ask it something an operator would actually ask:

> how many contacts do we have at Acme?
> export every contact at Acme as a CSV
> dedupe this list against Salesforce

This is the moment to decide whether you want to keep going. If the answers look useful, continue. If not, you have spent twenty minutes and installed nothing on your company's systems.

04Give it a brain (the AI key)

The agent needs access to a language model. The simplest route is Vercel's AI Gateway, which gets you many models behind one key.

In your Vercel dashboard, open AI Gateway and create an API key. Then open .env.local in any text editor and fill in three values:

AI_GATEWAY_API_KEY=your-key-here
AUTHORIZED_USER_EMAILS=you@company.com
MOPERATOR_SESSION_SECRET=paste-the-random-string-below

For that last one, generate a random string and paste the output in:

openssl rand -hex 32

AUTHORIZED_USER_EMAILS is your first and most important guardrail. Only the email addresses you list here can talk to the agent at all. Start with just your own and add colleagues later.

Now run it for real:

npm run agent

05Put it on the internet

So far it only runs while your terminal is open. Deploying puts it on a real URL that Slack can reach.

npx vercel deploy --prod

The first run asks a few setup questions — accept the defaults and log in with GitHub when prompted. One Vercel project serves the website, the admin pages, and the agent itself. Any scheduled digests in the repo become Vercel Cron Jobs automatically.

You also need to copy your keys into Vercel, since .env.local stays on your laptop. In your project's Settings → Environment Variables, add the same three values from step 4.

06Add it to Slack

One command scaffolds the Slack integration and walks you through creating the app:

npx eve add channel/slack

When it asks how to authenticate, choose Vercel Connect. That way Vercel manages the bot token, verifies that inbound requests genuinely came from Slack, and handles rotation — so no Slack secret ever sits in your environment.

You can skip Slack entirely if you want. The deployed app has a browser chat at /chat with the same agent, tools, and approval rules.

07Connect your real CRM

Adding an integration is just setting its credentials and restarting. The agent only shows itself tools for what you have configured, so it never offers to do something your install cannot do.

Each service has its own walkthrough in the repo under docs/ — for example setup-salesforce.md. The .env.example file lists every variable with a note on what it does and whether you need it.

08Lock it down before it touches real data

An agent with write access to your CRM deserves real thought. Here is the honest ladder, cheapest first — the first four cost nothing and matter most.

Free, and the ones that actually matter

Keep the authorised email list short. AUTHORIZED_USER_EMAILS is the front door. Everything else is secondary to who can open it.

Set your approver lists deliberately. In agent/lib/config.ts you decide who can approve CRM writes and, separately, who can approve ad-spend changes. Bulk-write thresholds and hard caps live here too.

Use a least-privilege integration user in every connected system, as in step 7.

Turn on Vercel Deployment Protection so the admin pages, the SOQL console, and the analytics views are not publicly reachable. Project Settings → Deployment Protection → enable Vercel Authentication.

If your CRM requires IP allowlisting

Some security teams will only open an API to known IP addresses. By default, traffic from Vercel can come from any IP, so there is nothing to allowlist. Two paid options fix that:

Whichever you choose, an IP allowlist is never the only control — you still authenticate with a token on top of it. And note that neither applies to Edge-runtime code, so keep the agent on the default Node.js runtime.

The repo has a fuller production checklist at docs/security.md.

09When something breaks

Run npm run agent:doctor first, every time. It makes one read-only call per integration and tells you which credential is actually wrong, which beats guessing from a stack trace.

Then read docs/fork-this.md, which covers making the agent genuinely yours — your naming conventions, your approval chain, your playbooks.