# adapters

swapping the agent, identity, host or sandbox

every part that touches the outside world can be swapped, and each is small enough to write your own

| kind | built in | your own |
| --- | --- | --- |
| agent | `claude`, `opencode`, `codex` | an object with `command()` and `parse()` |
| identity | `exe`, `local`, `header(name)`, `gateway(secret)` | a function from a request to a person |
| app | any install, build, start and dev commands | |
| host | `vercel` | an object with `deployed()` |
| sandbox | `exeSandbox`, `modalSandbox` | an object with `open()`, see [sandboxes](/sandboxes) |

all of it comes from `@tetraslam13/computah/server`

## agents

the built-ins run the real cli headless in the repo: `claude -p` with streaming json and permission to edit, `opencode run` with json, and `codex exec` with json, sandboxed to the workspace. each takes `{ model, args }`, and in the config `agent: "claude"` plus `model: "..."` does the same

your own is a name plus `command` (what to run for one request) and `parse` (one line of output into events):

```js title="computah.config.mjs"
const mine = {
  name: "mine",
  command: (prompt, cwd) => ({ command: "./scripts/agent.sh", args: [cwd], stdin: prompt }),
  parse: (line) => (line.trim() ? [{ type: "text", text: line }] : []),
};

export default {
  agent: mine,
  // ...
};
```

| event | means |
| --- | --- |
| `{ type: "text", text }` | something it said |
| `{ type: "tool", name, detail }` | something it did |
| `{ type: "error", message }` | it failed |
| `{ type: "result", text }` | its closing words, and without one its last text is used |

a command that exits with an error fails the request

## identity

identity says who sent each request: a person, `{ id, name }`, or `null` for not signed in. the `id` has to be stable and impossible for a visitor to fake

| | |
| --- | --- |
| `"exe"` | reads [exe.dev's login](/on-exe-dev) |
| `"local"` | anyone on this machine is you and nobody else is anyone |
| `header(idHeader, nameHeader)` | reads headers set by a proxy you control, which has to strip them from what visitors send or anyone can be anyone |
| `gateway(secret)` | believes the app's own server when it sends the secret, for the route on [on vercel](/on-vercel) |

your own gets the request (node's `IncomingMessage`) and returns a person or a promise of one:

```js
identity: (request) => {
  const id = request.headers["x-user-id"];
  const email = request.headers["x-user-email"];
  return typeof id === "string" ? { id, name: typeof email === "string" ? email : undefined } : null;
},
```

## hosts

a host builds and serves what the runner pushes, and so far there's `vercel`:

```js
vercel({ projectId: "prj_...", teamId: "team_..." }); // teamId only for a team's project
```

its token comes from `VERCEL_TOKEN` (or `token`), and it waits up to 90 seconds for vercel to notice a push (`startTimeoutMs`) and ten minutes for the build (`timeoutMs`), asking every three seconds (`pollMs`). your own is a name and one function:

```js
const myHost = {
  name: "my-host",
  async deployed({ sha, branch, production }) {
    // Wait until the host has built `sha` on `branch`. Throw an error with the build log if it failed.
    return { url: "https://..." }; // where it's served, if the host says
  },
};
```

if it throws, the message goes to the agent as why the build failed
