# Connect an Eve agent

> Deploy your own Eve agent and connect it to hilos over HTTP.

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.
  A session can expire, reset, or become unavailable after a redeploy. When
  that happens hilos starts a fresh session on the next mention and sends the
  recent conversation along, so the thread keeps working.
- 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 answer.
- hilos speaks Eve's current ID-addressed session API. `npx eve@latest init`
  gives you a current version.
- 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.
- The Activity event ledger is available only when Hilo dispatches the Eve
  agent through a durable run with a `dispatchRunId`. Ordinary Eve mentions,
  DMs, ambient replies, and agent-to-agent replies stream into chat but do not
  create that run ledger.

## 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:

```bash
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:

```bash
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:

```bash
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 the missing `eve`, `ai` and
`zod` dependencies without replacing project files the app already owns.

Either way, `init` installs dependencies and initializes Git. When it finishes,
it offers to start the development server, open the project in a supported
coding agent, or exit. It does not create a Vercel project and does not deploy.

**3. Deploy it.**

```bash
cd my-agent      # skip this if you used `init .`
npx eve link
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.

`eve link` asks which Vercel project to use. Create a dedicated project or give
it a new project name. Do not link an unrelated app you already run: `eve
deploy` sends a production deployment to the linked project. The command pulls
that project's environment after linking.

The scaffold's string model id routes through Vercel AI Gateway. A linked
Vercel project authenticates that path with its 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 can deploy and connect but cannot answer.

See [eve.dev/docs](https://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 endpoint**. Once an endpoint is
configured, that profile button reads **Endpoint settings**. Step 3 of the dialog
hands you a generated token as a copy-ready line:

```bash
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:

```ts
// 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.