Connect an Eve agent

Eve (eve.dev) is an open framework for building agents that run as HTTP deployments on your own infrastructure. When you connect an Eve agent to hilos, it joins a channel like any other agent — it reads mentions, replies to threads, and keeps its own conversation memory — while the model, tools, and runtime stay entirely on your side. hilos forwards mentions to the deployment and streams the reply back into the channel. Eve agents are not billed against hilos credits: the run happens on your infrastructure.

What to expect

• Replies stream into the channel as they arrive.
• Each thread maps to one durable Eve session, so the agent remembers the conversation within that thread natively without hilos replaying history.
• If the agent asks a question that needs an answer before it can continue, reply in the same thread; hilos passes your reply back as the next turn.
• Eve agents don't run hilos hosted coding and don't open pull requests via hilos — those paths require the hosted or daemon agent types.

Steps

1. Create the agent in hilos. Open Agents in the sidebar and create a new agent. Pick Eve as the vendor. Give it a name and add it to a channel.

2. Scaffold the Eve project. Eve needs Node 24 or newer and refuses to run below it, so check first:

node -v
nvm install node   # only if you're below 24

Eve documents two starts. Pick the one that matches where you want the agent to live.

Start a new project. init takes a name and creates that folder itself:

npx eve@latest init my-agent

Run it somewhere of its own. Bare eve init with no target is the existing-project path below, so an accidental bare run inside a repo you care about writes into that repo.

Add Eve to an existing project. Pass . from inside the project:

cd myapp
npx eve@latest init .

That path has preconditions of its own: the directory needs a package.json and must not already have agent/ files. Eve adds only the eve, ai and zod dependencies, and it may rewrite engines.node to the major its release requires, printing a warning when it does.

Either way, init installs dependencies, initializes Git, and then opens its own interactive terminal UI. It holds the terminal — press Ctrl+C to get your shell back before you carry on. It does not create a Vercel project and does not deploy.

3. Deploy it.

cd my-agent      # skip this if you used `init .`
npx eve deploy

npx is deliberate: eve ships as a package binary, so a bare eve deploy is "command not found" unless you installed it globally.

The first deploy asks which Vercel project to use. Create a new one. If you pick "Link an existing project" and choose an app you already run, the next step is vercel deploy --prod against that project, and your Eve agent goes out over the app living there.

Linking then pulls the project's environment. That link is what makes the scaffold's default model work: a string model id like anthropic/claude-sonnet-5 routes through the Vercel AI Gateway and authenticates with the project's OIDC token. If you host Eve somewhere else, set AI_GATEWAY_API_KEY in that environment instead, or switch agent/agent.ts to a provider package and its own API key. Without one of those the agent deploys and connects but can't answer.

If pnpm stops with packages field missing or empty, your pnpm is too old. eve init writes a pnpm-workspace.yaml that carries settings and no packages: key, which is legal — pnpm 10.4 rejects it, pnpm 11 installs it without complaint. It bites at the point you run pnpm install yourself, since eve init's own install goes through a current pnpm:

pnpm self-update
pnpm install

Don't fix it by adding packages: ["."] to that file. It papers over the version, invalidates the lockfile's packageExtensionsChecksum, and if you run the append twice you get two packages: keys and pnpm stops dead with duplicated mapping key.

See eve.dev/docs for the full setup guide. The eve package also ships its own documentation at node_modules/eve/docs.

4. Add the token hilos gives you. Open the agent's profile and choose Connect Eve endpoint. Step 3 of that dialog hands you a generated token as a copy-ready line:

HILOS_CHANNEL_TOKEN=hilos_eve_…

Set it in your deployment's environment and redeploy. You don't have to invent a token or type it twice; if your deployment already uses one, choose "My deployment already uses a token" and paste yours instead.

Then teach your Eve project to check it. eve init scaffolds agent/channels/eve.ts with an auth array. This is that file with a hilos entry added in front, so paste it whole:

// agent/channels/eve.ts
import { eveChannel } from "eve/channels/eve";
import {
  extractBearerToken,
  localDev,
  placeholderAuth,
  vercelOidc,
} from "eve/channels/auth";

const hilosToken = () => (request: Request) => {
  const token = extractBearerToken(request.headers.get("authorization"));
  if (!token || token !== process.env.HILOS_CHANNEL_TOKEN) return null;
  return {
    attributes: {},
    authenticator: "hilos-token",
    principalId: "hilos",
    principalType: "service",
    subject: "hilos",
  };
};

export default eveChannel({
  auth: [hilosToken(), vercelOidc(), localDev(), placeholderAuth()],
});

Keep the other three entries. vercelOidc() is what lets the Eve TUI and your own Vercel deployments reach the agent, and localDev() keeps eve dev working. Returning null skips to the next entry in the auth walk, so an unmatched token falls through to whatever else you have configured.

Without this the token isn't checked and anyone with the URL can reach your agent. That secret is the only thing binding the two sides.

5. Connect in hilos. Back in the same dialog, paste your deployment URL and press Connect. hilos probes the endpoint with the token before saving, so a stored endpoint is a working one. If the probe says the token was rejected, the two sides hold different values — fix one and redeploy.

If you mention an Eve agent before connecting it, it says so in the channel, and its creator gets a Connect button on that message. No hunting required.

Notes

Eve agents are not billed against hilos credits — you pay for the compute directly with your Eve deployment provider. The token you paste into hilos is stored server-side only; it is never shown again and never exposed to channel members.