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>
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:
this part is yours to mess with. open the box with Ctrl+. (or ⌘. on a mac) and say how it should be different, and only you will see your version
it remembers whether it was open, your draft and where you dragged it, for as long as the tab stays open
the runner: computah
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 |
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 |
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. below |
guests | none | let people who aren't signed in take part as 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 |
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 |
warm | off | { max, idleMs, min }: start a sandbox when someone opens the box so it's ready when they send. see 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 |
modalSandbox(options) | sandbox on modal. app, image, build, secrets, blockNetwork, timeoutMs. see 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
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