Kota guide
What Kota is
Kota is a shared folder you can open on the website and on your computers. Put a file in it on one computer and it appears on your other computers and on the website a moment later. Share a folder with someone and it appears in their Kota too.
Kota keeps earlier versions of your files, and when two people change the same text file at the same time, it combines both changes instead of keeping only one.
Signing in
Go to Sign in. There are two ways, and the first time is also how you make your account:
- Email: type your address. You get an email with a link and a six-digit code: open the link, or type the code on the page.
- Nostr: if you use Nostr, sign in with your browser extension, your signer app (Amber or another; scan the QR code or tap the button on your phone), or a bunker address.
Your name and picture come from your Nostr profile if you have one. Otherwise click your name at the bottom left (on a phone: top right) and open Account to set the name others see.
Spaces
Everything you keep in Kota is in a space: a folder with its files (and later its chat and meetings) that belongs to someone. Under Spaces you find all of yours in one list, and under each one who can see it. That comes only from whose space it is:
- 🔒 Only you: your own spaces, starting with My space.
- 👥 You and some people (a circle): exactly these people see it, like a group chat. Different people make another circle.
- ◎ A group's: its members see it, new members too (and the past with it).
- 🌐 Public: any space can be made public, so everyone in Kota can find it, view it (or also chat or edit) and add it to their list.
On a space's page, Files has its folders and files: make folders, upload (or drag onto the page), download, rename and delete. Access says why you can see it, who edits (everyone who sees it, or only its owner), whether it is public, and on which of your computers it is.
Inviting someone new
Invites are always to a group. On the group's page, its admins press Invite:
- A name of someone already in Kota adds them to the group at once.
- An email address: Kota emails them an invite; it works once.
- Copy link: send it any way you like; anyone with the link can join until it expires.
Whoever opens it signs in (or makes an account, the same step) and lands right in the group, with everything shared with it. The group's Members tab lists open invites and who joined through each; Withdraw stops one.
Server admins can also make a plain invite to Kota, with no group (Admin → Invites), to let people in and sort them into groups afterwards.
Groups and circles
A group is a named, lasting set of people. Under Groups, anyone can make one and becomes its admin. Its page has its Spaces, its Members with their roles (admin manages it, member edits its spaces, viewer only views), its Subgroups (such as a board: their members come from the group, and only they see the subgroup's spaces) and Settings (including who may invite).
A circle is you and a fixed set of people. Its people never change: under People → Circles, New circle from this one makes another with people added or left out, and moves its spaces along (or copies them, when someone is left out). Hide for me takes a circle's spaces off your list and computers.
People → All members lists everyone in Kota (name, picture and public spaces); tick private there to be seen only by people you share something with.
On your computer
On the Devices page press Add a computer: it shows the one line to paste for macOS, Linux and Windows (also on Get started). Then:
kota login
Your browser opens and asks to add this computer: check the code and approve.
kota install
Kota now syncs in the background, also after a restart. Your files are in the Kota folder in your home folder, by who can see them: Personal (yours), Circles, Groups/<group> and Public. Work there as with any folder. A space you only view is read-only there. Which spaces a computer keeps is set on each space's Access tab (and big group spaces start off).
Useful commands: kota status (is it in sync?), kota pause and kota resume. Everything else is on the Devices page: rename a computer, move its Kota folder, pause it, or remove it.
Ask your files: connect Claude
An AI assistant such as Claude can read and edit the files you can open, nothing more. Open Account → Connected apps and press Connect Claude: it shows the address to paste in Claude (Settings → Connectors → Add custom connector). Kota then asks you to approve. You can rename or revoke the connection there at any time; what it changes shows under Recent changes like anyone else's edits.
Agents: Claude Code on your computer, by voice
With the agents add-on, Claude (in the app, or by voice) can start Claude Code agents on your own computer, tell you what they are doing, pass them your words and stop them. They run under your own Claude login, and each one also shows in your Claude apps, where you answer its permission questions. It is off until you turn it on, per computer and per folder.
- Install Claude Code on the computer and sign in: run claude once in a terminal. Run it once in each repository agents will work in too, and accept the trust question.
- Add the computer to Kota (Devices → Add a computer).
- On that computer, allow the folder whose git repositories agents may work in:
kota agents allow ~/code
Only repositories inside allowed folders can be used, and only agents working there are visible to Kota. kota agents folders lists them; kota agents disallow ~/code takes one back. - Connect Claude to Kota (Account → Connected apps) and tick may start and steer agents on your computers.
- Ask Claude: "start an agent called game-sound in the game repository to add sound effects". Then "what are my agents doing?", "tell game-sound to use the free samples", "stop game-sound".
When the computer is asleep, Claude still answers from the last report, and messages wait until it connects. Each agent also gets a short status note in your files, under Agents. On the computer itself, kota agents list shows the same.
When something's wrong
- The sign-in email doesn't come.
- Wait a minute and look in your spam folder. You can ask for a new email after a minute; the old code then stops working.
- My files don't appear on my other computer.
- Run kota status on both. If it says offline, check the internet connection; if paused, run kota resume (or untick Paused on the Devices page). The Devices page shows a green dot for each computer that is connected now. Also check the space's Access tab: it may be switched off on that computer.
- My changes in a space don't reach the others.
- You may only be able to view it (its files are read-only on your computer, and a change made anyway is kept beside the file as a conflict copy). Ask its owner to let you edit.
- “Not enough space”.
- Each person and each group's spaces have a storage limit. Delete files you don't need, or ask the Kota admin for more.
- macOS or Windows warns about the program.
- That happens with a downloaded file because the program isn't signed yet. The one-line install on Get started avoids the warning. On macOS you can also right-click the file and choose Open.
- The code from kota login expired.
- Run kota login again; a code works for 15 minutes.
- Two files with “kide-conflict” in their name.
- Two people changed the same file at the same time and Kota couldn't combine them (pictures and other non-text files). Both versions are kept: open them, keep the one you want, delete the other.