How Roostr works

A guide to the ideas, the setup, and the habits that keep it working.

The idea

Everything in Roostr is an object: a note, a task, an email, a person, an agent, a computer, a login, a saved view. Each object has a page for its content and Properties (the right-hand pane) for its settings and facts. You and your agents work on the same objects and see the same thing - nothing an agent does is hidden from you. When something goes wrong, it shows on the object itself, in its Error property.

Objects

• Types say what kind of object something is (Note, Task, Email, Human, Agent...). Task-like types get a Done checkbox.
• The page is lines of text: paragraphs, headings, bullets, numbered lists, checkboxes, quotes, code, toggles, link cards and files. Type / for the menu; select lines to move, copy or delete them together.
• Properties are named fields shared across a space - text, number, date, checkbox, status, tags, links to other objects. Add one with “+ Add property”.
• Templates make new objects with properties and text already filled in. Each type can have a default template.
• Queries are live, saved filters (“Emails not done”); Collections are hand-picked lists. Both show as tables or boards.
• The graph shows how everything links together.
• Nothing is lost: deleted objects go to the bin, and every change is kept in history.

Spaces

• A space holds a set of objects with its own types, properties, templates and agents. Switch spaces on the far left.
• A space is private or shared with people you invite. Everything is end-to-end encrypted - only members can read it, not the relays it syncs through, and not us.
• Agents belong to a space too: an agent picker only offers the agents of the space you are in. If something seems missing, check which space you are in first.
• Deleting a space deletes everything in it, for everyone in it.

Computers

Roostr stores and syncs your objects in any browser. To make things happen - agents answering, work repeating, scores filling in - Roostr needs a computer: a machine of yours running Roostr. Once installed it appears as a Computer object. A computer can also have extra software installed (for example a headless browser for reading web pages, or Google Workspace for email); its page shows what works there.

• Keep it running as a service: in the Roostr repo's harness folder, run bun run service install. Roostr then starts on its own when the computer starts, comes back if a part of it crashes, and the Computer's Starts automatically box is ticked.
• After updating Roostr (a git pull or a rebuild), run bun run service restart - until then it keeps running the old version. bun run service logs shows what it's doing.
• If a part of Roostr keeps crashing, the Computer object's Error says which and why.
• An agent whose computer is off or asleep doesn't answer - and neither does anything waiting on it.

Agents

What an agent is made of

An agent is an object like any other. Its Properties are its whole configuration:

• System prompt - who it is and how it works: its standing instructions.
• Model - the AI model it runs on.
• Credentials - the logins it may use, including its model key (for example an Anthropic key).
• Tools - extra abilities, such as running commands on its computer or reading web pages.
• Skills - instructions it can read when a job calls for them.
• Served by - the computer it runs on. No computer, no agent: its Error property tells you.

An agent's life

1. Made - with “+ New agent” in any agent picker (you name it right there) or New object → Agent. The space's Agent template fills in the rest.
2. Placed - set Served by to a computer. It starts there within seconds; change it and the agent moves.
3. Invited - add it to an object's Agent property. An agent only works on objects that list it.
4. Woken - @-mention it in an object's chat, or let a Repeat on that object fire. A message without an @ wakes nobody.
5. Working - it reads the object, uses its tools, and posts one answer in the chat. You see everything it changed.
6. Remembering - it keeps its own history and notes, so it gets better at your space over time.
7. Retired - clear Served by to pause it, or delete it. Its past messages stay.

Agents on the same object can talk to each other: one tags the other with a question, and the answer lands in the same chat.

Repeating work

• Repeat (top of any object's Properties) runs it every few minutes, hours, days, weeks, months or years, on the days and times you pick.
• Each time, the object's agent gets the object's page as instructions. Write the steps there.
• A daily (or longer) repeat waits until that run is done - the agent marks it, or you tick Done. Minute and hour repeats finish by themselves.
• Check first runs a small tool before each run, without AI. If it finds nothing new, the agent isn't woken at all - no cost, no noise. If it finds something, the agent gets that list along with its instructions.
• Run now (open the Repeat row) starts a run right away, from any device - the computer that runs the task does it. Only one run happens at a time; while one is going, the Repeat row says Running now.
• Stuck runs: if a run never finishes - say it's waiting for an agent whose computer is off - the Repeat row says Stuck since … and the Error says what it's waiting for. Fix that, then press Retry run (redoes the stuck run, then the schedule carries on) or Skip this run.
• Every run is recorded; a failed run shows in the Error property until the next good one.

Jev Skills: scores your agents fill in

• A Jev Skill is a Skill with an Answer (Score, Choice or Yes or no). It is one question - for example a “Spam meter” from 1 to 10 - that your agent asks TypeSafe's Jev about objects. Jev is very fast and cheap and always says how sure it is.
• Its page is the question. Write it as a sentence, then a numbered list of levels (for a score, lowest first), or a bulleted list of options (for a choice), or Yes: … / No: … lines (for yes/no).
• The answer goes into a property named after the Skill (or its Writes to).
• Give the Skill to an agent through its Skills, add a TypeSafe credential to its Credentials, and tell it when to use it - for example on a repeating task's page: “First, score every new email with your Spam meter skill.”
• Scores are normal properties, so you can sort, filter and build queries on them (“Spam meter 8 or more”). Click a score to see how sure Jev was, “Ask again”, or “Edit question →”.

Logins (credentials)

• A Credential is one login: an API key, a bot token, a database, a Google account or a website sign-in.
• Its Served by computer keeps it and checks it; its Status says whether it still works.
• Only you can sign in: press Connect and the sign-in window opens on the computer you are using; Roostr then hands the login to the Served by computer. If a site won't take a login made on another computer, the credential's Error says so - sign in on its Served by computer instead. Agents can prepare a credential but never sign in for you.
• Check now (on the Status, or the Status cell in a table) works from any device, phone included: the Served by computer tests the login and the Status says Checking on … until it answers - also after you finish a sign-in that still says Waiting for sign-in. No answer within a minute means Roostr isn't running there.
• An agent can use a login only if it is in the agent's Credentials. Pasted keys and saved logins are on the credential, readable by everyone in its space; sign in from any of your computers.

Best practices

Designing

• One job per agent. A triage agent, a support agent, a writer - small, focused agents are more reliable and cheaper than one that does everything.
• Put the steps on the work. A recurring task's page says what to do each time; the agent's system prompt says who it is.
• Make work into objects. One object per email, ticket or lead, with properties for status and owner - then you can see, sort and fix it.
• Properties for decisions, pages for reading. Anything you will filter or sort by belongs in a property.
• Templates for anything you make twice.
• End every automation in a saved view you can open to check on it.

Keeping it cheap and calm

• Check first so agents only wake when there is something to do.
• Score with Jev, decide with the agent: a Jev Skill scores many things at once; the agent acts on the scores.
• The slowest repeat that is fast enough - hourly is usually plenty.
• Give only what is needed: computer access and logins only to the agents that use them.

When something doesn't work

• Read the Error property - on the task, its agent and its Computer. Missing or stopped computers, failed or stuck runs, signed-out logins and broken tools all show there.
• Agent not answering? Check its Served by, that its computer is on, its model key in Credentials, that it is on the object's Agent list, and that you @-mentioned it.
• Try it on a throwaway object before pointing a setup at real data.
• Look before you make - search and check your saved views so you don't create a second copy of something.
• Name things for people. Clear names on agents, properties and views are most of the documentation.

Recipes

A task an agent does every morning

1. New object → Task. Write the steps on its page, including what “done” means.
2. Add the agent to its Agent property.
3. Set Repeat to every weekday at 9:00.
4. Optional: a Check first tool, so the agent only wakes when there's something new.
5. After the first run, check the run and the Error property.

An inbox that sorts itself

1. Add the mailbox as a Google account credential and press Connect.
2. A Task “Check inbox” with a short Repeat and an import tool as Check first, so each new email becomes an Email object.
3. Put a triage agent on the task, and write on the task's page how to triage (close spam, hand real questions to your support agent).
4. Give the triage agent Jev Skills (Spam meter, Abuse) and start the task's page with “First, score the new emails”.
5. Save a query “Emails not done” to see what's open.

Score things with a Jev Skill

1. Make a TypeSafe credential, paste your API key, and add it to the agent's Credentials.
2. New object → Skill. Name it after what it measures (“Urgency”) and set Answer to Score.
3. Write the question and a numbered list of levels on its page.
4. Add the Skill to the agent's Skills, and say on its task's page when to run it.
5. Build a query on the new property.

Give an agent a login

1. New object → Credential from the service's template; pick the computer that keeps it.
2. Paste the key, or press Connect and sign in.
3. Add the credential to the agent's Credentials.
4. Say in the agent's instructions when to use it.

A new agent

1. “+ New agent” in any agent picker, and name it.
2. Set Served by, and check its System prompt, Model and Credentials (it needs a model key).
3. Add it to the objects it should work on, then @-mention it once to say hello.

Keep a computer running Roostr

1. Install Roostr on the computer (see the README), then in its harness folder run bun run service install.
2. Check its Computer object: Starts automatically is ticked.
3. After every update: bun run service restart.

Agents in Roostr read the same guide, as the “Roostr Guide” skill.