Coordination system for small-to-medium organizations and neighborhoods. Tasks, calendar, projects, members, groups, and skills under a per-house membership model.
See LinkKeys act-as access to let applications act for a user.
./tools dev # postgres (docker, host port 5433) + api + vite, sourcing .env.devThis starts Postgres in Docker, the Go API, and the Vite dev server, then
foregrounds a tail of logs/api.log + logs/vite.log (Ctrl-C just stops
the tail, not the services). The SPA is served at http://localhost:5173
and proxies /api/* to the API at localhost:6080.
.env.dev in the repo root holds local-only config (Postgres port, JWT
secret, dev-auth flag, initial admin identity) and is gitignored. With
LONGHOUSE_ENV=dev and dev-auth enabled, visit /dev-login in the SPA to
sign in without a live linkkeys identity provider.
Tear down with:
./tools dev-down # stops services, keeps the postgres volume./tools test # run all tests (API + webapp)
./tools test-api # run API tests only
./tools test-web # run webapp tests onlyapi/— Go API server (single CSIL-RPC endpoint, no REST)webapp/— Zest + TypeScript + Vite SPAclients/— generated CSIL client libraries, one package per languagecsil/— CSIL service/type definitions (source of truth for server + clients)coredb/— SQL migrations (goose)helm_chart/— Kubernetes Helm chartdeploy/— per-environment Helm values
The web app uses Zest and native DOM elements. It has no JSX compiler or application framework. The component library has two parts:
webapp/src/ui/supplies view lifetimes, DOM bindings, state, routing, and the Zest date field.webapp/src/components/supplies Longhouse controls. These include the task feed, editors, calendar controls, comments, and dependency controls.
LonghouseView extends Zest BaseComponent. Each page owns its subscriptions
and cleanup functions. State uses Zest BasicDataService. Navigation uses
Zest SimpleRouter. The date field extends Zest DateTimePicker.
webapp/src/styles/zest.css maps Zest color roles to the Longhouse palette.
Keep the explicit Vite CSS targets: they preserve light-dark() in the build.
To add a view, use el for DOM elements and live for values that change.
Use property getters for attributes that read state. Use When for conditional
content and Repeat for lists. Repeat keeps rows with the same object identity.
Keep row objects stable when a page of results arrives, or an open editor can
lose its draft. Use query for requests. It ignores responses after a source
change or page removal. Register timers and external listeners with cleanup.
Use defineView when a component needs its own Zest element and lifetime.
Use the generated client in data/clients.ts for API calls. Never send an empty
recurrenceFreq: the wire enum rejects it. On updates, use clearRecurrence
to remove a task or event schedule. Remote calendar edits also send the RRULE.
Deploy the API and web images together when introducing this field.
Run npm test and npm run build in webapp/. The tests include view cleanup,
request ordering, routing, task paging, and calendar acceptance and recovery.
Check native form behavior, focus, scrolling, and narrow layouts in a browser.
For a separate local API, set LONGHOUSE_DEV_API_TARGET before npm run dev.
Sign-in is delegated to linkkeys as the identity provider. Longhouse keeps a local member record that caches the identity data linkkeys releases; who may sign in is controlled by trusted domains and explicit user lists.
The Sign in button uses the instance's home IDP. Select Sign in with
another domain to enter name@domain.com. The browser saves this login
on the device and keeps it after sign-out. The saved login is only a form
value. It does not give access to Longhouse.
AuthService.BeginBrowserLogin checks the domain before it calls DNS or
LinkKeys. The home domain is permitted. Any other domain must be trusted by
at least one house. Longhouse reads the https= address from the domain's
_linkkeys_apis TXT record. It shows an error if the record is absent or
invalid, or if the lookup fails. It sends the local username to the IDP as
the username form value.
A signed, httpOnly longhouse_login cookie binds the domain and nonce to
the browser for ten minutes. The callback checks this cookie, current domain
trust, the assertion domain, nonce, and RP audience. Sign-in does not select
a house. The verified identity gets its active memberships across houses.
An unfinished sign-in from an older server version must start again after
this update.
The UI version comes from the release image's Git tag during CI builds.
CI passes it through the LONGHOUSE_APP_VERSION Docker build argument.
Local builds use version/VERSION.txt when that argument is absent. The
tag can precede the automatic update to that file. No UI file needs a manual
version change. Page responses require cache validation; hashed assets can
stay in the browser cache.
Longhouse sends its own claim request in Rp/sign-request
(linkkeys.LonghouseClaimRequest in api/internal/linkkeys/tcp.go). The
handle claim is required. A user who declines it cannot sign in. The
email, display_name, and avatar_url claims are optional. The RP server
does not need an RP_CLAIMS_CONFIG for Longhouse.
The request also names the application (application_id). LinkKeys 0.16.7
and later keep standing consent for each application, and the consent screen
shows the display name of the RP API-key account. The application ID comes
from LONGHOUSE_LINKKEYS_APPLICATION_ID. When that is empty, it comes from the
act-as key file (LONGHOUSE_ACT_AS_KEYS_FILE). Otherwise it is longhouse.
Keep it equal to the act-as application ID.
The bearer token snapshots the caller's per-house membership and roles at mint
time, so authorization needs no database lookup per request. Staleness is
bounded by the token's exp and by the AuthService.Refresh op.
Access bearers expire after 12 hours by default. Set
LONGHOUSE_BEARER_TTL_SECONDS to change this lifetime. CLI refresh sessions
expire after 30 days by default. Set LONGHOUSE_REFRESH_TOKEN_TTL_SECONDS to
change their absolute lifetime. Refresh-token rotation does not extend that
lifetime.
The release binary contains the API server and the Longhouse command-line interface (CLI). Sign in before you use resource commands:
longhouse auth login --url=https://longhouse.example
longhouse auth statusauth login opens a browser. The browser uses the normal linkkeys flow and asks
the user to approve the named CLI. For an SSH session, use --no-browser and
open the printed URL on another device. The old top-level login, status,
refresh, and logout commands remain as aliases.
The CLI stores named profiles in the operating system user configuration
directory. The profile file has mode 0600. Each signed-in profile contains a
short-lived access bearer and a rotating refresh token. The CLI does not print
these values.
longhouse profile add dev --url=https://longhouse.example
longhouse auth login --profile dev
longhouse profile use dev
longhouse profile house use HOUSE_IDUse noun and verb commands for Longhouse resources:
longhouse task list
longhouse task create "Repair the west gate" --due tomorrow
longhouse task done TASK_ID
longhouse project member add PROJECT_ID MEMBER_ID
longhouse comment add task:TASK_ID --body "Blocked by the permit"
longhouse dependency add task:TASK_ID project:PROJECT_IDA create or edit command shows a terminal form when required input is missing.
Use --interactive to request the form. Use --no-input to stop all prompts.
Plain text is the default output. Use JSON only when a program needs it:
longhouse task create --input task.json --output json
longhouse help task create --json
longhouse api describe TaskService.Create --jsonThe CLI converts local JSON to generated Go client types. It validates the
request and sends CBOR through the CSIL-RPC endpoint. It does not send JSON to
the server. Run longhouse help to see the command hierarchy. Run longhouse api list to see every generated CSIL operation. Automated callers can start
with longhouse agent instructions --json and longhouse help --json.
The account page lists CLI sessions. A user can revoke a session there. A revoked session cannot refresh again. Its current bearer can work until the configured bearer lifetime ends.
AGENTS.md— architecture, conventions, and the deploy/dogfood loopdocs/rbac.md— access levels, visibility, and the grant modeldocs/dependencies.md— task and project dependency edgesdocs/cli_approach.md— CLI hierarchy, input modes, validation, and output