You're reading the Keybase blog.
There are more posts.

When you're done, you can install Keybase.

September 18, 2017

Introducing Keybase Teams


Today we're launching the alpha of Keybase teams. It's the most important project in Keybase's history, and it brings together all of our work.

The basic idea

A Keybase team is a named group of people, with flexible membership. Let's say you work on a project called Treehouse. You could register treehouse on Keybase. This team name is universal; there can be only one Keybase team with a given name.

Teams get chats and channels. The chat looks a bit like Slack or Discord:

But Keybase teamwork is end-to-end encrypted, which means you don't have to worry about server hacks. Alternatively, you can lie awake at night...fearing a breach of your company's messaging history. What if your team's history got stolen from Slack and leaked or published? The legal and emotional nightmare.

Also, Keybase accounts are simpler; you don't have to switch at the top level of the app. Teams can be casual and small: bezosfamily. fort_greene_moms. mystery_authors. brooklyn_js. If a team is small, it'll blend into your inbox.

Teams with multiple chat channels are grouped under "Big teams."

Also, there is no upsell on message history. It's free to get to your old messages.


A team's encrypted files can be found in /keybase/team/:

This is only the beginning; the GUI is evolving fast and we'll have another announcement in ~2 weeks about encrypted git for teams. (Spoiler: truly private repos.)

Anyway, teams have signature chains

This isn't some malleable, trusted SQL database with team roles in it.

When you create a team, you begin a chain of signatures. Your first link declares that only you can append to the chain. You can then add other people. And technically, people themselves are chains, so you're signing their chains onto the team chain.

In the above, we see a chain of length 3, where treehouse now has 2 admins (barb and alice) and 1 "writer" (carter). Carter can write files and chats, but he cannot edit the signature chain, since he's not an admin.

How they would've done this, command-line edition


 keybase team create treehouse
 keybase team add-member treehouse --user=barb --role=admin

Then later, Barb:

 keybase team add-member treehouse --user=carter --role=writer

It's that easy. No one needs to understand cryptography. The Keybase app takes care of all the crazy stuff, such as rotating keys when Alice later boots Carter, because he's a lousy tree-friend.

There are a lot more specifics in the technical docs and our open source code.

It is live now

We're live today on desktop (macOS / linux / windows) and mobile (iOS / Android). You can start building teams and reserving your team names now.

However, for the next 4-8 weeks, administration of team membership & roles will be from the command-line. Meaning, someone on your team will need to know basic terminal usage. If that's ok, keep reading.

When in doubt

 keybase team --help # for admin'ing teams
 keybase chat --help # for admin'ing chat channels

Making and joining chat channels

Channel management is easy.

 keybase chat create-channel uber 'hr-issues'
 keybase chat join-channel fyre 'festival2018'
 keybase chat list-channels equifax # spoiler: none found

Important note A chat channel can be joined by anyone on a team. If you want to segregate chats, cryptographically, this is what subteams are for.

Subteams, quick 'n' easy

Actual companies, big and small, have another concern. Consider treehouse's devops team, or its board of directors. These groups have things to say and share that are absolutely private, just to them. From passing around technical secrets to discussing more tender business dealings, these groups will want data that can't be decrypted by others inside their own company.

Assuming you're an admin of treehouse, this works:

 keybase team create treehouse.hiring
 keybase team add-member treehouse.hiring --user=dahlia --role=writer
 keybase team add-member treehouse.hiring --user=evan   --role=admin
 keybase chat send treehouse.hiring "Ugg. Candidate asking for $12MM/yr."

You can invite someone into a subteam even if they're not in the parent team. We're already doing this at Keybase: our board of directors is inside keybase.bod.

Other uses: maybe treehouse.interns2018 or Or treehouse.vip_customers. That all works.

Team sigchain control is inherited. An admin of treehouse has keys for any subteams and can always add themselves.

Asking to join a team

If you know of a team, you can ask for access. Actually, I just made a team called keybasefriends so if you want to talk to other testers, ask for access:

 keybase team request-access keybasefriends

As an outsider, you can't tell who's on a team, so Keybase will ping the admins for you. They can then add you or ignore the request.

Communities, not just companies

You can create a Keybase team around any topic. Music. Cryptocurrencies. Writing. Games. Whatever you want. We're currently allowing up to 1,000 people into teams, but we'll expand this number as we make more improvements. If you build a community and want to promote it, let us know. We're curious what's happening in there (because we can't tell!).

keybase team create yoga
keybase team create guns_n_ammo
keybase team create dartmouth
keybase team create blackmirror
keybase team create okcupid_bdsm
keybase team create oh_god_the_ai
keybase team create bots_only
keybase team create is_anybody_still_alive

A taste of TOFU: quick team building by email


The following is a common desire, so we've made it work:

 keybase team add-member treehouse --role=writer

This emails sarah and walks her through joining your team, whether she's already on Keybase or not.

Invite-by-email is "Trust on First Use" (TOFU)...the same kind of TOFU you see when using Signal or WhatsApp to lookup a key by phone number.

Once Sarah is on the team, her identity can't be swapped out by a malicious server.

App updates every week

Expect to see team management features in the GUI in the coming days.

Give it a try!

❤️ the Keybase team


~ Anticipated q's ~

Why are team names universal?

So people can talk about a team name, safely, without using "key fingerprints" or many-digit "security codes."

What's stopping Keybase from having 2 different treehouse teams?

A team's signature chain is deterministically located in our Merkle tree. You can tell you're getting the same answer as everyone else, as described in our security docs.

Can't Keybase abuse its TOFU email feature to stick arbitrary people on my team?

No. First off, if you never use the feature, it can't be forced on you at all. It is triggered by a signed statement by you (the admin) into the team's sigchain, saying you want a single serving of TOFU, with the details. You can cancel that at any time with a revocation statement into the sigchain. You and all the other admins auto-audit this chain before accepting a recommendation from Keybase. You then mark the TOFU link as used.

The way it could be abused is for you to request a TOFU invite to but Keybase lies and tells you someone else owns that email. This is why it's called TOFU; you are trusting Keybase exactly once, at the beginning. If you never use it, you are trusting Keybase zero times.

The same will apply to invite-by-phone-number when we (probably) add that (controversial) feature.

Admin privileges cannot be granted with TOFU. Once your recipient joins, you can upgrade them afterwards.


Keybase servers do know team memberships: team names, users, and roles. Keybase servers cannot read the contents of chats or files or even know the names of chat channels or files, as they're end-to-end encrypted. At no point does Keybase have any private keys for any file or chat data. Your device keys never leave your device.

Why can't I rename top-level teams?

You can rename subteams, but top-level team renaming is not something we're ready to implement yet. It would require a level of redirection in our Merkle tree and, more important, extensive user experience considerations. So we may never implement it. If you dislike your team name, make a new team and invite everyone.

Can people outside my teams know what teams I'm in?

No, as mentioned in the metadata section above, the Keybase servers need to know, for a variety of user experience and notification reasons. But team sig chains are not published, unlike user sig chains, which are 100% public. Here's a view of my personal sigchain, which is public.

Can you explain the roles?

There's a great chart on this page, showing privileges, including what's cryptographically controlled vs. access-controlled.

Can you tell me more about subteam/team relationship?

A helpful list:

  • you can nest them:
  • to create a subteam you must be an admin of its parent
  • members of a team cannot tell the name or membership of subteams they're not a part of.
  • members of sibling teams cannot see each other's names or memberships. Lowly nike.interns2018 can't see nike.sweatshop.
  • subteams can be renamed, unlike root teams.
  • admin control is inherited; this prevents lost, orphaned subteams. If you admin nike then you also have admin control of nike.interns2018. Note you won't see its files/chats unless you explicitly join. Even though you have the keys, the Keybase server won't send you the encrypted data unless you sign yourself into the chain. (This is a form of access control, not cryptographic isolation, for reasons you can guess. It's crucial someone above interns2018 maintains control of its chain.)
  • members of a subteam can tell membership of parent teams; they need to play back those teams' chains to understand inherited admin privileges

What happens if I "reset" my account?

Account resetting on Keybase is where you throw away all your keys and start over, and redo your identity proofs. This cryptographically kicks you off all your teams, as you're no longer the person who was added. You will need to be added again. Admins will be notified when this happens.

If you're the last admin on a team and you reset your account, it will be orphaned forever. Teams themselves cannot be reset. Similarly, if all the admins of treehouse quit their jobs at the same time and refuse to cooperate, there is nothing Keybase can do to recover that team.

It has to be this way. Otherwise, Keybase could kick you out of a team, claiming you asked for a reset, and put someone else in your place.

Does this have forward secrecy?

It wouldn't be appropriate for a variety of reasons. Files and chat history need to be available to people and devices signed into the team after the data is posted or written to the filesystem. Elsewhere we've discussed our opinion that FS is a design mistake for most mainstream apps.

That said, it should be possible to go off-the-record when you want, and so we will be adding it as a mode. It just won't be on by default.

How does this fit into Keybase's business model?

We think someday if teams take off, we'll charge for larger teams. Nothing we're offering for free now will flip to a pay model, so if you make a 500 person team now and start using it, you won't someday be faced with a credit card screen just to get your files or messages.

Put most simply, we eventually want to find a way for actual enterprises to pay, while keeping personal and community use free. And any use now is grandfathered in.

How can I contribute?

Our project is open source and we do take PR's. Of course we're also hiring!


This is a post on the Keybase blog.