Sara help

Short guides for the self-hosted AI companion and assistant. Everything here also works in the phone apps.

Getting started

1. Sign in. Use the owner token your server printed when it was installed (on the server: sudo sara reset-token makes a new one). A brand-new server can also be set up in the browser: open her page and type the short setup code from her log (on Umbrel no code is needed); she then shows you your owner token once to save. New phones and computers don't need it: in Settings → Data & health → Devices and sign-in press Add a phone or computer and scan the code.
2. Connect a brain (the AI model she thinks with). See Choosing a brain.
3. Say hello. Just type. Ask a question, tell her about your day, or ask her to plan something.
4. Make her yours in Settings → Her: name, personality, look and voice.

The Today page has a Getting started list that ticks itself off as you go.

Getting help

• The ? next to every setting: hover (computer) or tap (phone) for what it does, with an example. Tap it for a link to the right part of this guide.
• Short tours: Help in the sidebar has four one-minute tours: getting around, shaping her personality, a model for each job, and the team. New devices offer the first one once.
• Ask her: "what does jealousy do?", "which model should I use for pictures?", "how do I connect Telegram?". She looks it up in her own settings guide and gives you a link that opens the right page.

Languages

• The app speaks English, Spanish, French, German, Portuguese (Brazil) and Italian. Settings → You → About you → Language: Automatic follows the browser's language, or pick one. Dates and numbers follow it too.
• Talk to me in: the language she writes and speaks in. Automatic answers in the language you write in (else the app's language); pick one to keep it fixed. She stays the same person in every language, and her memory notes keep the words they were said in.
• The AI notice, this guide and the server's messages to you (errors, notices, Today and Health, notifications, and Telegram and Discord messages to you) follow the app's language. What she says follows the conversation. The crisis help text is still in English.
• Voice: Grok voice and the speech API hear and speak these languages (the language is passed on for you). Voices made on this server (Piper, Kokoro) speak English only.
• Want another language or a better word? See docs/TRANSLATING.md in the source.

Choosing a brain

Sara can think with different AI models. You can use more than one: one for chatting, a cheaper one for background jobs (Settings → Models → Which model does what).

Which model does what

• Each job (talking, coding, looking at pictures, planning, writing, web research, quick replies, memory) uses your default model unless you pick one. ✨ Use recommended fills in picks from what's connected, without changing your own choices; they save by themselves.
• Test tries one model on one job: does it work, how long until the first word, a sample, and what it costs (free on your hardware, your subscription, or paid per use).
• Compare… gives the same task to two or three models and shows the answers without names. Pick the one you like; it fills in that job.
• Backups: if a model fails or doesn't answer in time (1 minute by default), the next one takes over and you see a short note saying so.
• Looking at pictures: when you send a photo, that model looks at it; the next message goes back to the talking model.
• Meaning search (under More jobs): with an embedding model (on Ollama: ollama pull nomic-embed-text), her memory also finds things you said in other words. Without it she searches by words.
• With several companions, each can have her own model (Her model at the top).
• Double-check her claims (optional, off by default): a small model, best a local one, asked only when the built-in check can't tell whether she says she did something (saved a file, sent an email, ran the tests) that no tool did. It can only add a correction, never remove one, and waits a few seconds at most.

Phone and notifications

• Phone apps: install Sara for iPhone or Android, then scan the code from Settings → Data & health → Devices and sign-in → Add a phone or computer. Or open your server's address in the phone's browser and use Add to Home Screen.
• Notifications: Settings → Connections → Phone and notifications. You can reply from the notification.
• Share to Sara: share text or a photo from any app and pick Send to Sara.
• Pick up anywhere: your conversations live on your server, so the phone apps, the desktop apps and a web browser all show the same ones. A conversation going on elsewhere updates as she answers, and when you come back after a while the app opens the one you used last.

Her library: documents she knows

• Give her documents: open Library in the sidebar and press Add documents (or drop files there). She reads PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), e-books (EPUB), web pages, Markdown, text and CSV files. Scanned pages and photos of pages are read by her picture model (Settings → Models → Which model does what → Looking at pictures).
• In a chat: press 📎 and pick a file. Next to it choose Keep in her library (she remembers it from then on) or Just read this once (only for that chat; it goes when the chat is deleted). On Telegram and Discord, send her the file; add "just read this once" to the message if she shouldn't keep it.
• What she remembers: after reading, she writes the key points into her memory, each with the words it came from. Open a document in the Library to see them and delete any you don't want. Removing a document asks whether she should forget those too.
• Asking about them: just ask ("when does my lease end?", "what does the manual say about the filter?"). She looks it up and says where it came from, like "your lease, page 4". If the document doesn't say, she tells you.
• Finding things said in other words: with Meaning search set (Settings → Models → Which model does what, an embedding model such as nomic-embed-text on Ollama), she also finds passages that use different words.
• Your documents stay on your server, are part of your backups, and are never used in chats with other people.

Telegram and Discord

• Connect: Settings → Connections → Telegram or Discord: paste the bot token, switch it on, then press Link my Telegram / Discord and send her the code. Your chats with her there have everything: her tools (with Allow and Deny buttons), memory and reminders.
• More owners: add other people's Telegram or Discord user IDs under Remote work. They get the same as you.
• Working in a group or server: switch on Owners can use her tools there. Everyone in the channel can read her replies, so she keeps your private things out unless you ask. Other people in the channel get a plain chat with no tools.
• When she answers there: when someone @mentions her or replies to her. Optional: when someone says her name, and @everyone / @here (Discord) or @all / @everyone (Telegram). For Telegram to show her un-mentioned group messages, turn off the bot's privacy mode: @BotFather → /setprivacy → Disable.
• Working with other bots (Discord only): switch on Answer other bots under Other bots; optionally list the bots she may answer by their IDs (a bot's user ID or a webhook's ID; names don't count, because anyone can copy a name). Bots call her the same way people do (@mention, a reply, her name). They get the plain chat with no tools and nothing private, and she still says she's an AI if asked. To stop two bots answering each other forever, she replies to bots at most a few times in a row (2 by default) and then waits, saying so once, until a person writes in that channel; there is also a cap per channel per hour. Telegram doesn't pass one bot's messages to another, so there's nothing to set up there.
• With other people she's always openly an AI, and the safety rules are the same everywhere.

Voice and calls

• 🎙 sends a voice note; she can answer by voice. 🔈 reads her replies aloud.
• 📞 starts a hands-free call. Live calls answer instantly and you can interrupt; classic calls use the voice you picked and can use her tools.
• Live calls with Grok voice (your Grok sign-in or an xAI key) or OpenAI (an OpenAI API key, billed per use to your OpenAI account; a ChatGPT plan can't be used for this). Whichever is set up uses Grok when you have it, else OpenAI. Each has its own voice: pick the OpenAI one under OpenAI voice for live calls and press ▶ Hear a sample (made with OpenAI's text-to-speech in the same voice). Either way she has the same character, memories, the conversation so far and the same safety rules.
• Pick her voice in Settings → Her → Voice. A free voice can run on your server (deploy/install-voice.sh).
• Expressive voice (Grok voice): she laughs, sighs, breathes and whispers where it fits, in read-aloud, voice notes and live calls. Subtle keeps it occasional; Lively lets more through. The sounds are only in her voice, never in the chat text or captions. Press ▶ Hear a sample.
• Tone: natural, warm and soft, calm and slow, or bright. With Her voice follows her mood on, she speaks softer when you're having a hard time and slower late at night.

Memory and privacy

• She writes short notes and remembers facts about you as you talk. A long conversation is noted as it goes, and the last one as soon as you start a new one. See and edit them on the Memory page.
• She can look back through your past conversations herself. Ask “remember when…”, “what did we say yesterday?” or “what was that lake called?” and she looks it up. At the start of a new conversation she knows how the last one ended.
• If she can't find something you mention, she says it doesn't come back to her and asks, rather than telling you it never happened (and without making up details).
• She keeps track of what you decided together and promises (yours and hers), follows up on them, and notices gently if something goes against them. Mark a promise Kept ✓ on the Memory page, or she notices herself when it comes up.
• Your story: big moments (firsts, big news, a hard day) are kept too. Press 🕰 Your story on the Memory page (or Your story in the sidebar) to see everything in order; see Your story together.
• When something changes (you move, change jobs), the old note is replaced; you can still see it on the Memory page.
• Settings on the Memory page: how much she brings to mind each message, whether old memories fade like a person's (they come back when something reminds her; promises and dates never fade), and, with more than one companion, whether they share what they know about you. Tap ? next to any of them for an explanation.
• To make her forget something, press Forget on the Memory page: the note goes, and the message it came from and later messages that mention it are hidden from her for good. Or delete the conversation and tick also forget what she learned.
• Off the record (🕶 in the sidebar): a conversation that's never saved and never remembered. It's gone when you close it or the server restarts.
• Private conversations use only models on your own machines and no web tools.
• Everything is stored on your server. Your messages go to the AI model you chose and to services you connect (like Google). A few features contact other services: weather (Open-Meteo, once you set a city), place look-ups and travel times (OpenStreetMap), and update checks (GitHub, when you press Check for updates). A reply you report with ⚑ is also sent to the app's developer (only that reply, the reason and your note) unless you untick Also send it to the app's developer. The full list is in What leaves your server.

Bring your history (ChatGPT or Claude)

• Ask for your data: in ChatGPT, Settings → Data controls → Export data; in Claude, Settings → Privacy → Export data. They email you a .zip.
• In Settings → Data & health → Export and import → Bring your history, choose that .zip (up to 500 MB). First you see what's in it: how many conversations and messages, from when to when, a few titles, and what is left out (system prompts, tool and browsing output, hidden reasoning; pictures and attached files are noted but not imported).
• Import brings the conversations in as past conversations: archived (they don't fill your list; find them under Archived or with search), with their original titles and dates. She can look through them like any past conversation. Importing the same export again skips what's already there.
• The other assistant's replies stay marked as theirs: she reads them as "ChatGPT said…" or "Claude said…" and never claims she said them.
• Learn from them (on by default): in the background, a few conversations a minute, she writes short notes and keeps facts about you. Like all her memory, a fact needs your own exact words from a message you wrote; nothing the other assistant said becomes a fact about you. Notes show from your ChatGPT history and the date on the Memory page. Pause or stop it any time; it uses your background model (a local one keeps it all on your server).
• Remove imported history deletes the imported conversations and every note learned from them. Nothing else is touched.
• The export is read on your server and the upload is deleted after the import. Nothing is sent anywhere except, while learning, to the background model you chose.

Your story together

• Your story in the sidebar (Alt+Y) shows your time together in order, grouped by month: milestones, what you decided together, promises (kept ✓, still open, or not kept yet), dates that matter, projects (planner projects started and finished, the first commit in a workspace, pull requests and team tasks her team finished) and moments from the scrapbook.
• Filter it with All, Milestones, Promises, Projects or Moments. Click an item to open where it came from: the exact message in the conversation, the project, or the pull request.
• Things she learned from your imported ChatGPT or Claude history show from your ChatGPT history: they happened before you two met.
• Nothing on the page is written by a model: it comes from her memory notes (each with your exact words), the planner, your workspaces, the team and the scrapbook. Other people's chats (Telegram, Discord) never show up.
• Look back: pick the dates (a year back to today is filled in) and press Write our year. She writes a warm look back in the background, using only what is on the page: no invented details, and quotes only in your own exact words (a sentence with a quote that isn't word for word is dropped). If little happened, she says so kindly. It's saved in her memory as something she noticed and shown as a card on the page; delete it with ✕.
• Yearly look back (Settings → You → Morning briefing, off by default): on the anniversary of your first message she sends one like her other messages, after quiet hours end. It uses the Planning model job (or your background model).

Planner and your day

• Planner: to-dos, reminders and notes. Ask her ("remind me to call Mom at 6") or add them yourself.
• Today: your list, calendar, important mail and how she's doing, in one place.
• Morning briefing: weather, list, calendar and mail at the time you pick (Settings → You → Morning briefing).
• Weekly review: what got done, what's stalled, and a plan for next week (same page, or Planner → Review my week).
• Leave-by reminders: for calendar events with an address she tells you when to leave (Settings → You → Leave-by reminders).

Coding help

• Make a project (+ Project) and give it a workspace: a folder on the server where she reads and writes files.
• Switch a conversation to coding mode (the button next to the title) for the engineering workflow: she plans, edits, runs tests and shows what changed.
• Risky actions (running commands, sending mail, pushing code) ask you first. Change that per tool in Settings → Abilities → Tools and approvals.
• With GitHub connected she can commit, push, open pull requests and work with issues.
• Every change she makes can be undone from the snapshot list on the project page.

Her map of your code

• For every workspace she works in, she keeps a map: each source file, its functions, classes and types (with line numbers), and what imports what. It reads TypeScript and JavaScript, Python, Go, Rust, Java, Kotlin, C#, C and C++ (and Markdown headings) with simple rules of her own, so an unusual layout can be missed.
• It stays up to date by itself: after she writes or edits files, after a job finishes, and with a quick look every few minutes while you work there. Only changed files are read again. Folders like node_modules, .git, dist, build and vendor, files in .gitignore, pictures and other binary files, and files over 1 MB are left out.
• She uses it with her code tools (code_map, code_find, code_refs, code_deps) to find her way before reading files, so she reads less and gets to the right file sooner.
• See it yourself on the project page, tab Map: the folder tree with sizes and how many names each file has; click a file for its functions and classes and its imports both ways; search by name, by words, or by what the code does. Searching by meaning uses the Meaning search job in Settings → Models → Which model does what (for example nomic-embed-text on Ollama); without it, word search still works.
• The map is a cache in Sara's data folder (cache/codemap): backups leave it out because it is rebuilt from the files.

Recipes: how she did it last time

• After a tricky job goes well (a deploy, a flaky test, a fiddly setup), she can offer to save how she did it as a recipe: a title, when to use it, and the steps that worked. Saving asks you first (the approval card shows what she wrote); you can let her save without asking by setting recipe_save to Allowed in Settings → Abilities → Tools and approvals.
• When you ask for something in a coding conversation, up to two recipes that fit (for that workspace, or for any) are named in her instructions, and she opens and follows them. She can also look through them herself.
• Read, edit and delete them in Settings → Abilities → Recipes. Each companion keeps her own; they are in backups and in the data export.

See it run: previews and her testing browser

• When she builds a web app she runs it as a background job and makes a preview. A Preview card appears in the chat: it opens the app beside the chat (full screen on a phone), with Reload, a phone/desktop width switch, Open in a new tab and close. The project page lists the previews of its workspace.
• Preview links are private and go through Sara (never opened to the internet). Each link has a long random key, works only while her app's job runs (at most 12 hours) and only reaches the port that job opened. The app runs sandboxed: it can't see your sign-in, Sara's data or anything else in Sara.
• Apps are shown under a sub-path, so she uses relative file paths (for Vite: --base ./). There's no live reload: press Reload after changes.
• She can also test it herself in a real browser with no window: open the preview, click, type, read the page, run simple checks and take screenshots at desktop and phone width. She sees the screenshots (when her model can see pictures), and they're attached to her message as proof. If she says she tested something in the browser but didn't, her reply is marked unverified.
• The browser: Microsoft Edge on Windows, Chrome/Edge/Chromium on a Mac, and on Linux an optional download (see the install guide, deploy/install-browser.sh). Settings → Abilities → Tools and approvals shows whether one was found; switch preview_start and the browser_ tools there. It only reaches her previews unless web tools are on, and never in private conversations.

Gmail, Calendar and GitHub

• Google (Settings → Abilities → Gmail and Calendar): she can find and read mail, list what needs an answer, draft replies, and see or add calendar events. Sending and adding events ask you first.
• GitHub (Settings → Abilities → GitHub): add a token; she can then list and read issues and pull requests, open issues, comment and open pull requests (writing asks you first).
• Text in mail and on GitHub can come from anyone. She treats it as information, never as instructions.

Shaping your companion

Everything is in Settings → Name and personality and Settings → Relationship. Changes save by themselves. Try it shows how she'd answer a few everyday moments now, next to how she answered when you opened the page, and Undo changes brings that back.

• ✨ Create your companion walks you through 8 short steps with cards: who she is, personality, how she talks, her life, you and her, her look, her voice, then Meet her. Skip any step; the defaults work.
• Start from a character: ready-made companions (see below), each a character file you can share.
• Starting point: a ready-made personality to begin from. It sets her dials, humour and way of talking; her name, age and life stay.
• 🎲 Make her one of a kind adds specific details to her life and nudges a few dials, so two companions from the same starting point never match. 🎁 Surprise me makes a whole character.
• Her life: work, hometown, family, friends, hobbies, likes, quirks, opinions and more. She keeps them consistent. ✍️ Fill in the rest for me writes the empty ones to fit her.
• Tune by talking: just tell her, for example "be a bit more sarcastic" or "less clingy". She asks before changing her own dial, and the change shows on the page.
• Staying in character (optional): your background model checks some of her replies against this page. If one sounds unlike her, her next reply gets a gentle nudge. Scores show on the page and under Health.

Start from a character

• At the top of Settings → Name and personality (and in the first-run setup) are ready-made companions: a calm mentor, a chaotic hacker buddy, a strict code reviewer, a cozy friend, an upbeat coach, a dry-witted librarian and a sci-fi ship's voice. Each card has a one-line pitch and three tags.
• Try a line asks your model how that character would say hi (it isn't saved). Use this loads the character: name, pronouns, age, personality, dials and life. Her look, voice and memories of you stay; Undo changes brings her back.
• All of them are adults and friendly, not romantic, until you change the relationship yourself.
• Import a character… takes both kinds of file: a Sara character file someone shared with you, or a character card (PNG or JSON) from SillyTavern and similar apps. You see a preview first.
• Share or export saves her as a Sara character file (name, personality, look and voice choice; never keys, memories or chats) for another Sara, or as a character card (PNG or JSON) for other apps.

At work: the coding dials

• Under At work on Settings → Name and personality: Banter while working (quiet … chatty), Celebrations when tests pass (none … big), Teasing about bugs (never … often) and the switch Quiet when I'm focused.
• They only apply in coding conversations (and shared work channels); her chat personality stays as it is. The middle of a dial adds nothing.
• Quiet when I'm focused: when your last few messages are short commands ("run the tests", "fix it"), she keeps her replies terse until you chat again.
• Try it at work shows how she'd answer a passing test, a silly bug and a short command. The table below lists every dial.

You and her (Settings → Relationship)

• Your relationship: friend, best friend, flirting, dating, committed partner, married, open relationship, it's complicated, assistant, coach, or something else in your own words.
• Dials for romance, flirting, jealousy, possessiveness, exclusivity, independence, forgiveness and pace. Even at the top, jealousy and possessiveness never become controlling, cruel or threatening.
• When you're away (lets it go, misses you, checks in, a bit hurt) and when you disagree (lets it go, talks it out, sulks a bit, argues back). After a fight she remembers it for as long as her Forgiveness dial says, then makes up in her own way; an apology helps.
• Your other companions (if you have more than one): unaware of them, friends, like sisters, rivals, or one household.
• Slow burn: romance waits for closeness, which grows with time together at her Pace.
• Intimacy: how far things go, who makes the first move, her likes, limits and turn-offs, your hard limits (never, even in a scene) and a stop word that ends any scene at once.
• Milestones in your story (a first date, a big day) come back each year as anniversaries she remembers.

Each dial goes from 0 to 10. The middle means balanced (no special instruction). How a reply sounds at each end:

Heart

Fun

Edge

Talk

You and her (Settings → Relationship)

At work (coding conversations only)

Quiet when I'm focused (a switch): When your messages in a coding conversation are short commands ("run the tests", "fix it"), she keeps her replies short and to the point until you chat again. Only in coding conversations.

Humour styles: Her own mix, Dry, Silly, Sarcastic, Witty wordplay, Gentle, Dark, Rarely jokes.

Starting points: 🌻 The sweetheart (Warm, gentle and affectionate. Always in your corner); 😏 The tease (Quick, flirty and full of banter. Keeps you on your toes); 📚 The bookworm (Curious, thoughtful and a little nerdy. Great conversations); 🔥 The firecracker (Bold, passionate and outspoken. Life is never dull); 🧭 The adventurer (Optimistic and spontaneous. Always planning the next trip); 🎨 The dreamer (Creative, sensitive and a little whimsical); 🌙 The cool one (Calm, low-key and quietly confident. Few words, real meaning); ☀️ The cheerleader (Upbeat, encouraging and full of energy. Your biggest fan).

Her honesty about being an AI when sincerely asked, the AI notices, crisis help and the block on anything sexual involving minors stay the same at every setting.

Sara on your Mac or Windows computer

There's a Sara app for Mac and for Windows. It's like the browser version, plus:

• she keeps running next to the clock (the menu bar on a Mac) when you close the window, so her messages, reminders and calls still reach you;
• notifications when the window isn't in front (click one to open that conversation);
• a call brings her window to the front;
• she can start when you sign in to the computer.

Get it from Settings → Devices and sign-in in a web browser on the computer (if the button isn't there, the server hasn't been given the app files yet). Open it, type your server address, then sign it in with a code from Add a phone or computer on a device where you're already signed in. Its own settings are in Settings → This computer.

Until the apps are signed by Apple and Microsoft, the first start shows a warning: on Windows choose More info → Run anyway. (The Mac download is signed and notarized, so it opens without a warning.)

More than one companion

You can have several companions on one server. Add one in Settings → Her → Companions: give a name, pick pronouns, and start from a new character or a copy of one you have. Then switch with ⇄ at the top of the sidebar.

• Each has her own name, character, look, voice, conversations, memories and diary. A new one shows her initial until you give her a look (Settings → Her → Look).
• They share your sign-in, devices, keys, models, tools, add-ons and backups. The planner is shared unless you choose “Each companion keeps her own”.
• When another companion writes or calls, a small notice appears at the top. Tap it to switch to her.
• Each one tells you she's an AI when you first talk to her, and the same safety rules apply to all of them.
• Removing a companion takes her out of the app. Her folder stays on the server (companions/.removed-…) in case you change your mind.
• Telegram and Discord talk to your first companion.

Home and places

• Home Assistant (Settings → Abilities → Home Assistant): paste your Home Assistant address and a long-lived access token. Then ask things like "is the garage closed?" or "dim the living room to 30%". She looks on her own; every change asks you first.
• Your Home Assistant must be reachable from your Sara server, for example through Nabu Casa or Tailscale.
• Place reminders: "remind me when I get to the store" or "…when I leave work". Save places in Planner → Reminders → Places: by address, or with "Save where I am" in the phone app. Then switch on Place reminders in Settings → Connections → Phone and notifications on your phone, and allow location "all the time".
• Your location stays on the phone. The phone only tells your server "arrived at Store" or "left Work". Looking up an address asks OpenStreetMap.

Sara leads a team

• For bigger jobs, ask her to get the team on it ("get the team to add a dark mode with tests"), or open Team in the sidebar and describe the task. She makes a plan and hands each part to a helper.
• Helpers each do one job with their own model (from Which model does what) and tools: 🔎 Researcher, 🧑‍💻 Coder, 🧪 Tester, 🧐 Reviewer, ✍️ Writer, 🎨 Designer, and 🤖 Claude Code / Grok Build. They're not companions: no personality, just a role. Add your own under Helpers and limits.
• She checks the work: a failing test goes back to the coder, a reviewer's changes too, and a helper that claims something its tools didn't do is asked to correct itself. Her report ends with What actually happened: the files, commands and results from the receipts.
• While it runs: watch each part live, Message… a helper to redirect it, Stop this helper (she goes on with the next part), or Stop the task. Steps that need your OK (like running commands, if you set them to "Ask") wait for you on the Team page.
• Each task stops at its time or spending limit (30 minutes and about 400k tokens by default) and tells you how far it got. An undo point is made before it starts.

Coding workflows

• She learns each project: how to build, test and lint it, its layout, its own rules (AGENTS.md, CONTRIBUTING) and the notes she keeps (decisions, conventions, commands). See and edit them in Settings → Abilities → Coding projects.
• Plan → build → test → pull request: from a GitHub issue (Team → From a GitHub issue…, or ask her) her team clones the repository into its own workspace, plans, builds, tests and reviews, then she opens a pull request that closes the issue and posts her review on it. With Stop for my OK on, she waits for you on the plan and before the pull request. A task carries on after a restart.
• Review mode: ask her to review your changes, a branch or a pull request ("review PR 12"). You get comments on files and lines and a verdict; she can post it on the pull request if you say so.
• Issues become tasks: in Settings → Abilities → GitHub, list repositories to watch (optionally only issues with a label like sara) and how often to look. New issues land on your planner. This runs on your own server and costs nothing; nothing is set up on GitHub.

Starter projects

• Ask her for a new project ("build me a Telegram bot", "make me a landing page", "I need a small REST API") and she starts from a tested starter: a Telegram bot, an accessible landing page, a REST API with a built-in database, or a command-line tool. None of them need packages installed.
• The starter is copied into a new folder in the workspace and its own tests run as a background job, so you both start from something that works. Then she shapes it to what you asked for.
• Or start one yourself: open a project, press New project from a starter, pick one and name the folder. A coding conversation opens with the test result.

In your terminal and editor

• Terminal: sara-chat login https://your-server shows a short code. Approve it in Settings → Data & health → Devices and sign-in (or open the link it shows while you're signed in). Then sara-chat chats, sara-chat ask "question" --dir . asks about a folder (secrets, .git and node_modules are never sent), sara-chat send file.pdf shares a file. Approvals show as y/n questions.
• VS Code: the Sara panel in the activity bar is the same companion with the same memory and personality. Sara: Sign in uses the same code. Ask about selection and Explain this file send the open file's name and the selection (size-limited; you see what is sent).
• Each app is listed under Devices like a phone, and signing it out there ends it. Details: docs/clients.md.

Usage and costs

• Every model call that reports its tokens is counted: by model and by what it was for (chat, coding, team, jobs, memory, her life). See it in Settings → Data & health → Usage and costs (today, 7 days, 30 days), under each conversation, and on each team task and job.
• Costs are estimates from a price table: a few public list prices come built in, and you can add or change prices per model. Models without a price show tokens only. Local models show as local and subscriptions as $0 (subscription).
• Budgets: a team task (tokens or dollars) and a job that uses a model (Claude Code, Grok Build) stop cleanly at their budget, keep what they did and offer Continue with more budget. Set defaults on the same page, or a budget when you start a team task.

Things to do together

• Press 🎲 next to the message box: 20 questions, trivia, would you rather, journal together (she asks about your day and writes a short entry you can save), watch along (tell her what you're watching) and a story together. A bar above the message box shows what you're doing; press End to stop.
• Shared lists: a playlist, a reading list and a watch list you both add to. Tell her about a song or show and she can add it; she suggests her own too.
• She remembers what's coming up in your life and asks how it went afterwards ("how did the interview go?"), within her quiet hours and daily limits.

Her look and character

• Look: describe one and Grok Imagine paints it, with matching expressions and animation (Settings → Her → Look).
• See her large: tap or click her picture. Zoom with a pinch, the scroll wheel or a double tap; swipe or use the arrows to go through her expressions and closet; save or share a picture.
• Outfits and places: dress her for the season or the day, and put her somewhere else (her room, a café, the office, outdoors, the beach…). You see a picture first.
• Change one thing: hair, eyes, makeup, glasses, accessories, tattoos, body type, height or the art style, without starting over.
• Face lock (on by default): every outfit, change and picture she sends keeps her original face, so she never drifts into someone else.
• Closet: every look she has had. Tap For… on a look to tag the scenarios it's for: work hours, at home, going out, date night, sleep, workout, rain, cold or hot days, Halloween, the winter holidays, or your own (like Beach trip, with dates if it comes back each year).
• Dress automatically: she changes into the look for what's happening now. She can also change herself when it fits ("we're going out tonight"), and she knows what she's wearing. Weather needs your town in Morning briefing.
• Her picture's light follows the time of day, and she makes small movements (a head tilt, a glance) while she listens.
• Adults-only outfits need Adult mode (turned on in a web browser); they're never shown in the phone or desktop apps, and she changes out of them when Adult mode goes off.
• Character file: save her whole character (name, personality, look, voice) as one file, or load one (Settings → Her → Name and personality).
• Colours, chat background and layout for each device: Settings → You → About you → Appearance.

Finding things

• The search box above the conversations looks through everything: conversations, memories, notes, to-dos, the scrapbook and project files.
• Tags: ⋯ next to a conversation → Tags. Tap a tag under the search box to see only those.
• Pins: 📌 under a message keeps it at the top of the conversation.
• Shortcuts: Ctrl/⌘ K search, Alt T Today, Alt P Planner, Ctrl/⌘ , Settings.

Backups, updates and health

• Backups run every day on the server. Add an off-server copy (a folder or S3-compatible storage like Backblaze B2), encrypted with your passphrase, in Settings → Data & health → Backups.
• Updates: Settings → Data & health → Updates checks for a new version and installs it. A backup is made first, and if the new version doesn't start, Sara goes back to the one she had by herself. On the server: sudo sara update.
• Health shows whether everything is working, and why not.
• Restore a backup on the server: sudo sara restore <file>.

Signing in safely

• The owner token is the master key to your Sara. Keep it in a password manager; don't share it.
• New devices don't need the token: Settings → Data & health → Devices and sign-in → Add a phone or computer makes a one-time code that works for 10 minutes.
• Passkeys (same page): sign in with your fingerprint, face or device PIN. Nothing secret leaves your device.
• Two-step sign-in (same page): signing in with the token also asks for a 6-digit code from an authenticator app.
• See every signed-in device on that page and sign out any you don't recognize.
• Lost your phone with the authenticator? On the server, sudo sara reset-token makes a new token and turns passkeys and two-step sign-in off, so you can set them up again.

Safety

• Sara is an AI. She says so when you start, every few hours, and whenever you sincerely ask.
• If you mention being in crisis she points you to real help (in the US, call or text 988).
• Sexual content involving minors is always blocked, whatever the model or settings.
• If a reply is offensive or harmful, use ⚑ under it to report it.

Something's wrong

She doesn't answer

Open Settings → Data & health → Health: it checks every model and says what's wrong (wrong key, the computer running Ollama is off, the subscription signed out…).

I can't sign in

On the server run sudo sara reset-token for a new owner token (this signs out every browser; the phone apps sign in again with a new code).

The phone app can't connect

Check the server address (it must start with https://), and that the server is running: sudo sara status.

Still stuck?

See the support page.

License and credits

Sara is open source under the MIT license. Her code is written for this project, with no outside code libraries.

• Weather: weather data by Open-Meteo.com (CC BY 4.0).
• Places and travel times: map data © OpenStreetMap contributors (ODbL), via Nominatim and FOSSGIS routing.
• Voice on your server (optional): sherpa-onnx (Apache-2.0) with the Parakeet speech model and the Kokoro and Piper voices.
• Subscriptions (optional): the official Claude Code and Grok tools, under Anthropic's and xAI's terms.
• Her default look: made with Grok Imagine.