The Bel's handbook for House of Ur

What House of Ur is

House of Ur gives you a private House for working with AI servitors — long-running Dubsars, specialist workers, a House Library, public Sites, optional custom Domains, Vault credentials, and House settings in Bel's Chamber.

Your signed-in identity is separate from any one House. You may keep zero, one, or many Houses. Each House has exactly one Bel (owner). Others may dwell there as Ashibu. People of a House are managed in Household.

This alpha is intentionally small. It is not open public signup. New Houses need a house permit code. Joining someone else's House needs a House invite from their Bel. Once you are inside a House: use Dubsars for ongoing work, keep documents in the Library, publish folders as Sites when you want a public URL, and keep secrets in The Vault.

Bel and Ashibu

Bel is the title for the human owner of a House — one Bel per House. Bel owns billing, House settings, Vault secrets, House API keys, and inviting people into the Household.

Ashibu (Akkadian āšibu, a dweller / resident) is the title for a welcome member of the Household. Ashibu share day-to-day work: Hall, Library, Sites, Domains, Dubsars, Impressions. Treasury and Bel's Chamber are read-only for Ashibu. Vault secrets and House API keys stay Bel-only. Ashibu may leave a House; they cannot remove the Bel.

Your account may be Bel in one House and Ashibu in another. The product labels the role for the House you are standing in. Bel name and Bel-facing messages still refer to the House's Bel; Ashibu are named as themselves when they speak.

Start here

If you are brand new, pick the path that matches what you were given.

Create a House (house permit)

1. Sign in with GitHub or Google at https://app.house-of-ur.com/signin (or the appdev host on the development stack).
2. Create House and enter your house permit code. That code creates a new House and makes you its Bel. Each additional House needs its own permit.
3. Set your House slug in Bel's Chamber if prompted. The slug becomes part of every built-in Sites hostname ({site}-{house}.house-of-ur.com).
4. Enter the House. You can use House Hall, Library, Sites, Domains, Vault, Household, and Impressions without subscribing first.
5. Subscribe in Treasury when you want AI. Dubsar wakes, servitor chat, web search, and creating new servitors need an active plan (and Shekel balance). Billing is per House.
6. Create your first Dubsar (or publish a Library folder as a Site — that part does not require Treasury). Invite collaborators from Household when you are ready.

Join a House (House invite)

1. Open the invite link you were given (/join/…). Sign in with GitHub or Google if you are not already signed in.
2. Accept the invite. You become Ashibu of that House. You do not create a House, and you do not become Bel.
3. Work in the House. Use the rooms your Bel has opened. If you need billing changes, Vault secrets, or more invites, ask the Bel.

Household

Household is the people room of the current House — members, pending invites, and leave / remove. Bel's Chamber is House settings. Treasury is money. Household is people.

House invite links expire after a short time and show the token only once when minted. Pending invites never expose the raw token again. If you keep more than one House, switch Houses from the app chrome; URLs include the House id so a shared link returns to the same House.

Houses and rooms

Your House is easiest to understand as a small set of rooms with clear jobs.

House Hall

House Hall is the foyer. It orients you, surfaces the latest Daily Tablet entry, and sends you onward to the rooms where work happens.

Servitors' Quarters

Create and manage your workforce. For most meaningful ongoing work, start with a Dubsar.

House Library

The Library is for files and folders: reference material, notes, prompts, images, datasets, and working documents. Sites publish a chosen Library path; content stays in the Library as the source of truth.

The Vault

The Vault is for credentials, not documents. If a value would be dangerous to leave in a normal file, it belongs here. OpenRouter and Brave are not configured here — they come from Treasury. Ashibu do not manage Vault secrets.

Bel's Chamber

Bel's Chamber holds Bel name, timezone, and your House slug. Provider billing is managed in Treasury. Account-level profile and Create House live in user settings, not here. Ashibu can open Bel's Chamber to read House details; only the Bel changes them.

Servitor choices

A servitor is a worker you create for a specific style of job. In this alpha, most Houses should lean toward Dubsars first and treat the other types as more specialized tools.

In broad terms, capability runs Dubsar → Igigi → Apkallu → Kalu. More capable workers often want stronger (and usually more expensive) models.

Dubsars

A Dubsar is a long-lived, event-sourced worker with a timeline, identity, work list, timers, messaging, and a shell. While awake it can use tools, read and write Library material, and run shell commands in a House-provisioned MicroVM executor (the primary path for Dubsar shell work).

You shape a Dubsar by talking to it on the timeline. Over time its Identity and Work List reflect the role and standing instructions you want it to carry forward.

Main model vs maintenance model

The main model handles core agentic work. The maintenance model handles lighter upkeep stages and can often be smaller and cheaper.

Sleep / wake cycle

• Asleep: default; nothing running, no spend.
• An event arrives: Bel message, webhook, timer, or another Dubsar — then Awake.
• Awake: process the event and Work List until nothing left to do.
• Maintenance: update Identity / Work List, then back to Asleep.

Model guidance for Dubsars

The picker is the OpenRouter model list. Experiment is normal.

• deepseek/deepseek-v4-pro — current default main model for new Dubsars.
• deepseek/deepseek-v4-flash — current default maintenance model for new Dubsars.
• openai/gpt-5.3-codex — strong agentic main-model option.
• openai/gpt-5.4-mini — cheap and useful, especially as maintenance.
• z-ai/glm-5 — cheap, competent Dubsar option.
• google/gemini-3-flash-preview — cheap; do not trust it with anything important.

Timeline first

The timeline shows messages, wakes, timers, and tool activity (including shell cards with a human-readable reason). If you want to understand what a Dubsar has been doing, start there.

Timers and recurring work

Ask for things like tomorrow at 9am… or every Monday…. Timers are a major reason Dubsars beat one-off chats for ongoing responsibilities.

Webhook input

External systems can POST into a Dubsar timeline. In Settings, enable webhooks and create a webhook code. Send to:

POST https://app.house-of-ur.com/api/houses/{houseId}/webhook/{dubsarId}
Header: X-Webhook-Code: {your-code}
(or Authorization: Bearer {your-code}, or ?code=)

On the development stack, use https://appdev.house-of-ur.com instead.

Dubsars and Library files

Dubsars can read and maintain Library files, and their MicroVM can sync selected folders for shell work (subject to size limits). Prefer the Library for durable documents; use the shell for ephemeral computation.

Dubsars working together

You can ask one Dubsar to consult or instruct another — useful for hand-offs and specialization.

Optional payload logging

By default Impressions stores usage metadata (model, tokens, search queries) without full prompts/responses. For debugging a specific Dubsar, open Settings → Edit → Impressions logging and enable full LLM and/or web-search bodies (about seven days retention). Turn it off when finished — payloads can contain secrets.

Library and Vault

If it should behave like a document, put it in the Library. If it is a secret, put it in The Vault.

Publish from the Library

From a Library folder you can create a Site that serves that path. Badges and links in the Library help you jump between the folder and its Site.

Sites

A Site publishes a Library folder as a public website on House of Ur infrastructure. The Library remains the source of truth; the Site is the public edge.

Built-in hostname

• Production: {siteSlug}-{houseSlug}.house-of-ur.com
• Development: {siteSlug}-{houseSlug}-dev.house-of-ur.com

That built-in URL always remains available, even after you attach a custom hostname under Domains.

Modes

Cache

Library writes do not automatically flush the public CDN. When visitors should see fresh files, open the Site and use Refresh cache.

Rename

You can rename a Site slug while it has only the built-in hostname. Rename is blocked while a custom hostname is attached — detach first, rename, then re-attach if needed.

Provision status

New Sites provision asynchronously. Stay on the Site detail until status settles. If something looks stuck, try again later or use reconcile from the Site detail when offered; see Troubleshooting.

Domains

Domains lets you bring a registrar-owned domain into your House without changing nameservers. House of Ur never takes over your DNS zone. You paste specific records we show you.

1. Add a domain in the Domains room (for example sites.example.com or example.com — whichever DNS zone you control for the labels you will attach).
2. Prove ownership by creating the TXT (or instructed) verify record, then click verify. Status moves to verified when public DNS matches.
3. Attach to a Site from Site detail: pick the verified domain and a subdomain label (for example label articles on domain sites.example.com → articles.sites.example.com). One custom hostname per Site.
4. Finish certificate + traffic DNS: paste the ACM validation CNAME(s), wait until the certificate is ready, then CNAME the hostname to the CloudFront target shown in the UI. Use Check to refresh status.

Treasury

Treasury is subscription and billing for AI provider usage. House of Ur bills through Paddle. Usage is metered in Shekels (₪) and visible in Impressions and Usage charts.

Without an active subscription you can still sign in, use Library / Sites / Domains, store non-provider secrets in The Vault, and read messages — but servitor LLM work, web search, and creating new servitors require Treasury.

Plans (typical)

Pricing model: 1 USD = 30 ₪. Included allowance refreshes with the plan; purchased top-up packs do not expire the same way. You can buy Small / Medium / Large packs, enable auto top-up when balance runs low, and optionally set a daily spend cap.

When Shekels hit zero (on a normal House), provider work stops until you top up or renew. A daily cap, if set, can also block provider calls for the rest of the day.

OpenRouter

OpenRouter is the model gateway behind House of Ur. Every LLM request from your servitors goes through House of Ur's platform OpenRouter account, gated by Treasury. You do not create or paste your own OpenRouter API key in the app.

1. Sign in and create or join a House (permit or House invite).
2. Subscribe in Treasury when you want model access (Bel).
3. Create servitors and pick models from the in-app list (sourced from OpenRouter).

Brave Search

Live web search for supported servitors uses Brave Search on platform keys, included with your Treasury subscription. You do not add Brave API keys in The Vault.

Impressions

Impressions is the House's record of facts: what happened, when, and who was involved. Open it from the sidebar under the current House (/house/{houseId}/impressions). Usage charts live at /house/{houseId}/impressions/charts. Bel and Ashibu can both read Impressions.

• Usage rows — OpenRouter completions and Brave searches (cost metadata, tokens, queries).
• Audit rows — sign-ins and similar house events.

Charts aggregate cost (USD estimate), tokens, and request counts for the House, a provider, or one servitor. Impressions is not a full replacement for OpenRouter's own activity pages; it is your House ledger.

Common workflows

First useful Dubsar

1. Subscribe in Treasury (if you have not already).
2. Create a Dubsar in Servitors' Quarters.
3. Tell it who it is and what it owns on the timeline.
4. Point it at a Library folder if it should maintain documents.

Publish a simple site

1. Put an index.html (or markdown site tree) in a Library folder.
2. Create a Site from Sites or from the Library publish flow.
3. Wait for provision; open the built-in hostname.
4. After edits, use Refresh cache when visitors should see the new files.
5. Optionally verify a Domain and attach a custom hostname.

Invite someone into your House

1. As Bel, open Household.
2. Mint a House invite and share the link (not a house permit code).
3. They sign in, accept, and become Ashibu of this House.

Credentials for external systems

1. Store the secret in The Vault.
2. Grant visibility to the Dubsar that should use it.
3. Ask the Dubsar to use that credential — do not paste long-lived secrets into the timeline if you can avoid it.

API reference

This section is for technical Bels and agent builders who want to call House APIs directly. It covers House-scoped HTTP endpoints Bel can use with a session or House API key. It is not a catalog of internal gateway actions.

Conventions

Auth

Browser Bels obtain tokens via social OAuth (sign-in chooser → /auth/github or /auth/google → callback → access + refresh tokens). Refresh with POST /auth/token/refresh. Logout: POST /auth/logout.

For scripts, create a House API key in the app, then exchange it:

POST /auth/token/apikey
{"api_key":"cou_ak_…"}

→ {"access_token":"…", …}

Then call /api/… with that bearer token. Keys are House-scoped; treat them like passwords.

Health

Houses

House routes are scoped under /api/houses/{houseId}/…. Authorization is membership in that House (and role for Bel-only writes). Session tokens are user-scoped; they do not embed a House id.

Library

Sites

{"site_slug":"docs","library_path":"/public/docs","configuration":{"mode":"static"}}

Domains

Servitors and sessions

Dubsars

Treasury (billing)

All under /api/houses/{houseId}/billing/…. Common reads/actions:

• GET …/tiers, GET …/tier-prices, GET …/packs, GET …/pack-prices
• GET …/projection — balance / plan projection
• PUT …/selection, POST …/checkout, POST …/pack-checkout
• PUT …/daily-spend-cap, PATCH …/settings, GET …/auto-topup/eligibility
• POST …/portal-session — Paddle customer portal

Impressions

House API keys

curl -s https://appdev.house-of-ur.com/api/houses/$HOUSE_ID/sites \
  -H "Authorization: Bearer $TOKEN"

Troubleshooting

Mesopotamian theming

House of Ur borrows names from ancient Mesopotamia as atmosphere, not as a history lesson. Bel, Ashibu, Dubsar, House Hall, Library, Treasury, Household, and Impressions are product labels first. Use the glossary when a word is unfamiliar.

Glossary