# reference

every prop, flag and config field

every prop, flag and config field, as the source has them. it's the long boring card, sorry

## the box: `<Computah>`

```tsx
import { Computah } from "@tetraslam13/computah";
```

| prop | default | |
| --- | --- | --- |
| `hotkey` | `"mod+."` | opens and closes it. `mod` is ⌘ on a mac and ctrl elsewhere, and `ctrl`, `meta`, `shift`, `alt` join with `+` |
| `title` | `"improvements"` | the window's title |
| `launcher` | `true` | the small button that opens it |
| `defaultOpen` | `false` | start open |
| `endpoint` | found for you | where the runner is. unset, it tries `/__computah` on the page's own address, then `http://127.0.0.1:4821` but only on pages from this machine (`localhost`, `127.0.0.1`). no runner found anywhere else means no box |
| `secret` | none | bearer token, for a runner started with `--secret` |

you can try a `hotkey` here:

_(on the web page there's a little interactive piece here, `apps/docs/playground/reference.tsx`, that visitors can change by typing into the box)_

it remembers whether it was open, your draft and where you dragged it, for as long as the tab stays open

## the runner: `computah`

```sh
computah [options] [-- <command to run alongside, e.g. next dev>]
computah serve [--config computah.config.mjs] [--port 8000] [--cwd .]
```

| flag | default | |
| --- | --- | --- |
| `--agent` | first one installed | `claude`, `opencode` or `codex` |
| `--model` | the agent's own | model passed to the agent |
| `--port` | `4821` | where it listens |
| `--host` | `127.0.0.1` | anything else needs `--secret` |
| `--secret` | `COMPUTAH_SECRET` | required bearer token |
| `--origin` | none | allow a page from another address. once per address |
| `--no-commit` | | leave changes uncommitted |
| `--cwd` | here | the repo to work in |
| `--help` | | prints this |

for `computah serve`, `--config` is the config file, `--port` overrides the config's port and `--cwd` is the repo

## the config: `computah.config.mjs`

`computah serve` reads its default export

| field | default | |
| --- | --- | --- |
| `agent` | first one installed | `"claude"`, `"opencode"`, `"codex"`, or an [agent object](/adapters) |
| `model` | | passed to a built-in agent |
| `app` | | how to install, build and run it. below |
| `identity` | required | `"exe"`, `"local"`, or a function from request to person. see [adapters](/adapters) |
| `trust` | required, at least one owner | who may do what. below |
| `port` | `8000` | where it listens |
| `host` | `"0.0.0.0"` | which interface |
| `idleMs` | 20 minutes | stop a personal copy unused this long |
| `agentEnv` | | extra env vars for the agent |
| `release` | build and serve here | `{ push: { ... } }` to push to a host instead. below |
| `repairs` | `3` | tries the agent gets to fix a change that doesn't build |
| `sandbox` | none | run the agent in a [sandbox](/sandboxes). below |
| `guests` | none | let people who aren't signed in take part as [guests](/guests). below |
| `maxCopies` | no limit | personal copies running at once, one more stops the oldest-used |
| `pieces` | none | globs of files that each hold one browser-only component importing only `react`. a version that only changed those is swapped into everyone's build and never built. see [letting anyone change it](/guests) |
| `maxAgents` | `6` | agents working at once across everyone, the rest wait their turn |
| `maxBuilds` | `1` | builds running at once. one next build uses about 4 cpus, so `2` is right for a machine with 8, and on mine 3 was no faster than 2 |

### `app`

each command runs in a shell in the app's folder, with `PORT` set

| field | default | |
| --- | --- | --- |
| `dir` | repo root | the app's folder inside the repo |
| `install` | | installs deps in a fresh copy, like `pnpm install --frozen-lockfile` |
| `build` | | builds a copy for serving, like `pnpm build` |
| `start` | required, unless pushing | serves the built copy on `$PORT`, like `pnpm start` |
| `dev` | | a hot-reloading copy on `$PORT` for watching live |
| `health` | `"/"` | the path that answers when it's up |
| `startTimeoutMs` | 90 seconds | how long a copy gets to start answering |
| `env` | | extra env vars for every command |

### `trust`

| field | default | |
| --- | --- | --- |
| `owners` | required | ids or names (emails work) |
| `trusted` | nobody | same, for trusted people |
| `members` | nobody | a list, or `"everyone"` signed in |
| `memberPaths` | anything | globs from the repo root a member's change may touch |
| `memberNote` | none | one sentence for members. shown in their box |
| `memberRules` | `memberNote` | rules for the agent, beyond `memberPaths` |
| `memberCheck` | none | `(files: { path, content }[]) => string or null`, given new contents (`null` if deleted), returns why it's not okay or `null`. `clientOnly()` is one |
| `memberDailyLimit` | `20` | requests per member per day |
| `dailyLimit` | no limit | requests per day, all members together |

### `release.push`

| field | default | |
| --- | --- | --- |
| `remote` | `"origin"` | git remote to push to |
| `branch` | `"main"` | the branch the host serves to everyone |
| `host` | none | who builds what's pushed. without one, a change counts as live once the push lands |
| `check` | `true` when `app.build` is set | build on the runner before pushing |

### `sandbox`

| field | default | |
| --- | --- | --- |
| `in` | required | a `Sandbox`: `exeSandbox()`, `modalSandbox()`, or [your own](/sandboxes) |
| `warm` | off | `{ max, idleMs, min }`: start a sandbox when someone opens the box so it's ready when they send. see [sandboxes](/sandboxes) |
| `for` | `"members"` | `"members"`: everyone who isn't owner or trusted. `"everyone"`: every request |

### `guests`

needs `trust.members: "everyone"`.

| field | default | |
| --- | --- | --- |
| `secret` | required | signs the cookie that remembers each guest |
| `forgetMs` | never | deletes a guest's version once they've been gone this long |

## server helpers

all of these come from `@tetraslam13/computah/server`

| helper | |
| --- | --- |
| `clientOnly({ imports })` | a `memberCheck`: files must start with `"use client"`, can't contain `"use server"`, can't be deleted or load code by a computed name, and import only `imports` (default `["react"]`) |
| `exeSandbox(options)` | sandbox on exe.dev. `egress`, `setup`, `ssh`, `prefix`. see [sandboxes](/sandboxes) |
| `modalSandbox(options)` | sandbox on modal. `app`, `image`, `build`, `secrets`, `blockNetwork`, `timeoutMs`. see [sandboxes](/sandboxes) |
| `vercel(options)` | a host. `projectId` (required), `teamId`, `token` (default `VERCEL_TOKEN`), `timeoutMs` (10 minutes), `startTimeoutMs` (90 seconds), `pollMs` (3 seconds) |
| `gateway(secret)` | identity that believes the app's server when it sends `secret`. pairs with `createProxy` |
| `header(idHeader, nameHeader)` | identity from headers set by a proxy you control |
| `exe()`, `local()` | what `"exe"` and `"local"` mean |

## the route: `createProxy`

```ts
import { createProxy } from "@tetraslam13/computah/next";
```

| option | default | |
| --- | --- | --- |
| `runner` | required | the runner's address, like `https://runner.example.com` |
| `secret` | required | the secret the runner's `gateway(secret)` got |
| `identify` | required | `(request) => ({ id, name }) or null`, from your app's sign-in |
| `basePath` | `"/api/computah"` | where the route is mounted |

it returns `{ GET, POST }`

## everything the server entry exports

from `@tetraslam13/computah/server`:

- **agents.** `claude`, `opencode`, `codex`, `agents`
- **identities.** `exe`, `local`, `header`, `gateway`
- **member check.** `clientOnly`
- **host.** `vercel`
- **sandboxes.** `exeSandbox`, `modalSandbox`
- **types for your own parts.** `Trust`, `Person`, `Identity`, `Sandbox`, `SandboxSession`, `Host`, `PushOptions`, and more
- **for your own runner.** `Computah`, `Site`, `serve`, `createRunnerServer`, `createFrontServer`, `buildPrompt`, with their types
