Setup guide

From download to your first task in about fifteen minutes. Every step can be changed later in Settings.

Install on Windows

Download Twarita-Setup-<version>.exe from the Download page.
Open it. If Windows shows Windows protected your PC, choose More info, then Run anyway. The installer isn't code-signed yet; you can check the download first.
Follow the installer. It installs for you only and needs no administrator rights.
At the end, choose Start Twarita now. Next time, open Twarita from the Start menu.

Your agent uses its own window of Google Chrome or Microsoft Edge for websites. If neither is installed, the installer says so; install one, then carry on.

First start

The first start takes a little longer while Twarita prepares itself. It then opens in its own window, already signed in.

Closing the window keeps Twarita running in the corner of the taskbar, so scheduled work carries on. To stop it completely, click its icon there and choose Quit Twarita.
Run the short setup. Open the account menu at the bottom of the sidebar, then Help, then Setup guide. It takes about five minutes and you can skip any step: where it runs, your AI, about you (your CV), channels, tools, safety and a first goal.
Pick a safety level. Cautious asks before every action that changes something. Balanced asks before paying, sending, submitting, deleting, installing or sharing your data. Autopilot with limits acts on its own within your daily limits. Payments always need your approval.

Connect an AI provider

Twarita needs an AI to think with. OpenRouter is a simple choice: one key gives access to many models. You pay OpenRouter for what you use.

On openrouter.ai, create an account, add some credit and create an API key.
In Twarita, open Settings, then Models and costs. (In the setup, this is the Your AI step.)
Next to OpenRouter, choose Connect OpenRouter, paste the key and choose Save to vault. The key goes straight to your vault and is never shown again.
The row now says To let Twarita reach OpenRouter, allow openrouter.ai. Choose Allow openrouter.ai.
It shows Waiting for your approval in Inbox. Choose Open Inbox, check that the card is about openrouter.ai, and choose Approve.
Back in Models and costs, OpenRouter shows Site allowed. You're ready.

Why the extra step? Twarita's Guardian lets your agents reach only the websites a task needs or you allow, so a working key isn't enough on its own. Models that run on this computer, through Ollama or LM Studio, need no website approval.

Linux desktop

The Linux desktop app is a .deb package for Ubuntu 22.04 or 24.04, or Debian 12, 64-bit. When the Download page lists it:

Download twarita_<version>_amd64.deb.
In a terminal, in the folder you saved it to, run sudo apt install ./twarita_<version>_amd64.deb.
Open Twarita from the app menu, then carry on with First start and Connect an AI provider.

Your data lives in ~/.local/share/Twarita. sudo apt remove twarita removes the app and keeps your data.
On Debian 12 with GNOME, Twarita's icon in the top bar needs the AppIndicator extension (the gnome-shell-extension-appindicator package).

If the Download page says Coming soon, run Twarita on your own server instead.

Your own server, controlled from your phone

On a server, Twarita works around the clock and your phone becomes its remote control, with an icon on your home screen. Nothing on the server is open to the internet: your devices reach it through Tailscale, a free private network that only your own devices can join.

What you need

A server with Ubuntu 22.04 or 24.04, or Debian 12 or 13, with 4 GB of memory and 15 GB of free disk. A small cloud server or an old PC at home both work. You need to log in to it (usually with ssh) and use sudo.
A free Tailscale account, and your phone.
About 30 minutes, mostly waiting while the server builds Twarita the first time.

1. Install on the server

Bring the server up to date: sudo apt update && sudo apt upgrade -y
Copy the Twarita folder to the server, go into it and run sudo ./packaging/server/install.sh. It installs Docker if needed, builds Twarita (10 to 30 minutes the first time) and starts it. Keep the window open.
When it shows a Tailscale sign-in link, open it on any device, sign in and choose Connect. If it asks you to turn on HTTPS for your tailnet, enable MagicDNS and HTTPS Certificates in Tailscale's DNS settings.
Recommended: in Tailscale's list of machines, open twarita's menu and choose Disable key expiry.
At the end it prints your Twarita address (like https://twarita.tail1234.ts.net) and a pairing code, which works once, for 5 minutes. Need a new one? Run sudo twarita-pairing-code.
Back up /opt/twarita/secrets/vault_key somewhere safe, such as a password manager. Without it, the passwords Twarita stores can't be read.

2. Connect your phone

Install the Tailscale app, sign in with the same account and switch it on.
Open your Twarita address in Safari (iPhone) or Chrome (Android). The first visit can take a minute.
On Connect to Twarita, choose Pair this device with a code, type the code, name your phone and choose Pair this device.
In Settings, then Devices and security, choose Add a passkey for this device. Next time, just choose Sign in with a passkey.
Add Twarita to your home screen: on iPhone, Share, then Add to Home Screen; on Android, the menu, then Install app.

To update the server, run the install command again: your data, vault key and Tailscale connection stay. Phone notifications aren't available yet.

Update or uninstall

Update on Windows: quit Twarita (Quit Twarita from its taskbar icon), then run the newer installer. Your data and settings stay.
Uninstall on Windows: use Uninstall Twarita in the Start menu, or Settings, then Apps. Your data is kept unless you tick Also delete my data.
Where your data lives on Windows: %LOCALAPPDATA%\Twarita. Saved passwords are kept in Windows Credential Manager.

Troubleshooting

What you see	What to do
“Windows protected your PC”	The installer isn't code-signed yet. Choose More info, then Run anyway.
“Waiting for your approval in Inbox”	The change waits for you. Open Inbox and choose Approve on its card. If you denied it, choose Allow again.
“Twarita's Guardian blocked a website”	Your agents may only reach websites you allow. If you trust the site, add it in Settings, then Trust Centre, then Allowed websites, and approve it in Inbox. For an AI provider, use Allow on its row in Models and costs.
“No AI provider is connected yet”	Follow Connect an AI provider.
“All agents paused. Nothing will run until you resume.”	Someone chose Pause all. Choose Resume at the top of the window when you're ready.
The installer won't update Twarita	Twarita is still running. Choose Quit Twarita from its taskbar icon, then run the installer again.
A message says Twarita couldn't start	Start it again from the Start menu. If it keeps happening, the message names its log file, in `%LOCALAPPDATA%\Twarita\logs`. Settings, then Health and logs, checks every part.
The phone can't reach your server	Open the Tailscale app: it must be on and signed in to the same account as the server.