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";
propdefault
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
launchertruethe small button that opens it
defaultOpenfalsestart open
endpointfound for youwhere 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
secretnonebearer token, for a runner started with --secret

you can try a hotkey here:

yours to change

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

shell
computah [options] [-- <command to run alongside, e.g. next dev>]
computah serve [--config computah.config.mjs] [--port 8000] [--cwd .]
flagdefault
--agentfirst one installedclaude, opencode or codex
--modelthe agent's ownmodel passed to the agent
--port4821where it listens
--host127.0.0.1anything else needs --secret
--secretCOMPUTAH_SECRETrequired bearer token
--originnoneallow a page from another address. once per address
--no-commitleave changes uncommitted
--cwdherethe repo to work in
--helpprints 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

fielddefault
agentfirst one installed"claude", "opencode", "codex", or an agent object
modelpassed to a built-in agent
apphow to install, build and run it. below
identityrequired"exe", "local", or a function from request to person. see adapters
trustrequired, at least one ownerwho may do what. below
port8000where it listens
host"0.0.0.0"which interface
idleMs20 minutesstop a personal copy unused this long
agentEnvextra env vars for the agent
releasebuild and serve here{ push: { ... } } to push to a host instead. below
repairs3tries the agent gets to fix a change that doesn't build
sandboxnonerun the agent in a sandbox. below
guestsnonelet people who aren't signed in take part as guests. below
maxCopiesno limitpersonal copies running at once, one more stops the oldest-used
piecesnoneglobs 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
maxAgents6agents working at once across everyone, the rest wait their turn
maxBuilds1builds 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

fielddefault
dirrepo rootthe app's folder inside the repo
installinstalls deps in a fresh copy, like pnpm install --frozen-lockfile
buildbuilds a copy for serving, like pnpm build
startrequired, unless pushingserves the built copy on $PORT, like pnpm start
deva hot-reloading copy on $PORT for watching live
health"/"the path that answers when it's up
startTimeoutMs90 secondshow long a copy gets to start answering
envextra env vars for every command

trust

fielddefault
ownersrequiredids or names (emails work)
trustednobodysame, for trusted people
membersnobodya list, or "everyone" signed in
memberPathsanythingglobs from the repo root a member's change may touch
memberNotenoneone sentence for members. shown in their box
memberRulesmemberNoterules for the agent, beyond memberPaths
memberChecknone(files: { path, content }[]) => string or null, given new contents (null if deleted), returns why it's not okay or null. clientOnly() is one
memberDailyLimit20requests per member per day
dailyLimitno limitrequests per day, all members together

release.push

fielddefault
remote"origin"git remote to push to
branch"main"the branch the host serves to everyone
hostnonewho builds what's pushed. without one, a change counts as live once the push lands
checktrue when app.build is setbuild on the runner before pushing

sandbox

fielddefault
inrequireda Sandbox: exeSandbox(), modalSandbox(), or your own
warmoff{ 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".

fielddefault
secretrequiredsigns the cookie that remembers each guest
forgetMsneverdeletes 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

typescript
import { createProxy } from "@tetraslam13/computah/next";
optiondefault
runnerrequiredthe runner's address, like https://runner.example.com
secretrequiredthe secret the runner's gateway(secret) got
identifyrequired(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