# keybase/client: Building the Keybase Apps From Source

> The keybase/client repository holds the Go crypto core, the keybase service and CLI, plus the Electron and React Native apps. It is a monorepo for people who want to read or modify Keybase, not a quick install path.

**keybase/client** — Keybase Go Library, Client, Service, OS X, iOS, Android, Electron

- Repository: https://github.com/keybase/client
- Stars: 9,251 · Forks: 1,284
- Language: Go
- License: BSD-3-Clause
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/keybase-client

## What keybase/client Actually Contains

This is not a single application. It is the source for a family of clients that all talk to Keybase services, and the repository README says all of the macOS, Windows, Linux, iOS and Android apps are developed here. The top-level layout reflects that: go holds the core crypto libraries, the Keybase service and the command line client; shared/desktop is the Electron desktop application; shared/android and shared/ios are React Native apps; osx is a separate macOS app developed in parallel to the Electron one; protocol defines the Avro-based wire format clients use to talk to Keybase services; packaging holds the release scripts. If you are looking for a library to embed, the go directory is the part you want. If you want to understand how a Keybase client authenticates or encrypts, the protocol directory is the specification you read first. The repository also carries media assets, pvl-tools, rnmodules and a skill directory, which tells you this is a working monorepo rather than a curated distribution.

## The Go Service, the CLI and the Protocol Layer

The architecture separates a long-running local service from the user-facing clients. The go directory contains the service and the keybase command line client, and the README links a troubleshooting document at go/doc/troubleshooting.md for problems with that CLI. Clients do not reimplement cryptography per platform; they speak to the service over a protocol defined in the protocol directory using Avro. That is the mechanism that lets an Electron app, a React Native app and a native macOS app share the same cryptographic behaviour. The practical consequence is that the Go layer is the security-relevant surface. If you are auditing Keybase, reading shared/desktop tells you about UI state handling, while reading go tells you what actually happens to keys and messages. The README does not document the service's internal request lifecycle, so treat the protocol definitions and the Go source as the authoritative description rather than the top-level README.

## Installing the Toolchain and Running a First Command

The README does not give a from-source build recipe for the whole repository. It gives a development-guidelines section for git hooks and points users who simply want Keybase installed to the release downloads page. What the README does document is enabling the pre-commit hooks that the project uses to check commits. Install the pre-commit utility first, then wire it into the repository:

```bash
pip install pre-commit
rm .git/hooks/pre-commit
pre-commit install
```

The README lists brew install pre-commit as the alternative on macOS. After pre-commit install, the hooks run on subsequent commits, and the README says to proceed as normal from there. For the command line client itself, the README directs you to go/doc/troubleshooting.md when something goes wrong, which is the closest thing to operational documentation in the top-level file. Note the warning printed at the top of the README: things in this repository are explorations, and a build from source might not do what it says it is doing. That is the project's own words, and it is the reason the README pushes ordinary users toward released builds rather than a self-compiled binary.

## The Docker Compose Stack Is Not the Client

The repository root contains a docker-compose.yml, and it is easy to misread as a way to run Keybase. It is not. The services defined there are mysql.local, sqsd.local and kbweb.local, and they reference images from a private Amazon ECR registry at 897413463132.dkr.ecr.us-east-1.amazonaws.com. The kbweb service sets KEYBASE_RUN_MODE=devel and binds several ports including 3000, 9911, 13009, 13010, 13037 and 13047, with a startup entrypoint of run/startup_for_container.sh. This is a development backend for the web-facing side, and because the images come from a private registry you cannot pull them without credentials. The README does mention Docker image releases, but it points at packaging/linux/docker/README.md for those, which is a different artifact from this compose file. If your goal is a desktop or mobile client, the compose file is irrelevant to you.

## External Pull Requests Do Not Get CI

One limitation is stated plainly and matters if you plan to contribute. The README says that if you forked the repository on GitHub and opened a pull request, it will show as having failed Jenkins CI, because the project does not build external PRs without a review first. Only after a member of the Keybase team reviews your changes are the commits merged to a branch on the primary fork and built from there. For a contributor this means the red CI status on your PR is expected and not a signal about your code. It also means the feedback loop depends on maintainer attention rather than on automated checks you can trigger yourself. The README does not describe a timeline for that review, and it does not document any alternate CI path for outside contributors.

## Where keybase/client Is the Wrong Tool

If you want an end-to-end encrypted chat or file sharing component that you can drop into an existing product, this repository is the wrong shape. It is the full client stack for one service, with a protocol layer defined in Avro and a local Go service that clients connect to. You would be adopting the protocol, the service and the client conventions together, not a library with a narrow interface. The README's own warning reinforces this: some things here are explorations, and the built app might not behave as advertised. A team that needs a maintained, versioned crypto library with a stable API should look elsewhere, and a team that needs an installable Keybase should use the released builds. The repository is for reading, modifying and rebuilding Keybase itself. That is a legitimate and useful purpose, but it is a different purpose from integration.

## Maintenance, Licensing and Upgrade Cost

The repository is not archived, and the most recent release listed is v6.6.3 on 2026-06-03, following v6.6.2 on 2026-04-08 and v6.6.0 on 2026-03-06. The last push to the default branch was on 2026-09-21. If you track the master branch rather than a release tag, you are consuming unreleased work, and the README's warning about explorations applies most strongly there. On licensing, the README states that most code is released under the New BSD (3 Clause) License and that where subdirectories include a different license, that license applies instead. That second clause is the one to check before redistributing anything: the top-level LICENSE file alone does not settle the terms for every directory, and the repository has enough distinct subtrees that a blanket assumption is unsafe. The README also carries a cryptography notice, stating that the distribution includes cryptographic software and that the country you reside in may restrict import, possession, use or re-export. That is a factual constraint on redistribution, not a formality.

## Conclusion

Adopt keybase/client if you intend to read the crypto code, port the service, or work on the CLI; the repository is where the Go core, protocol definitions and all five client apps live. Do not adopt it as an installation route, because the README explicitly warns that a build from source might not do what it says it is doing and points ordinary users to the release downloads instead. Before committing, verify the subdirectory licences, since the README states that where a subdirectory carries a different licence, that licence applies, and confirm that your build target is one of the platforms listed rather than an unsupported one.

## FAQ

### How do I install keybase/client from source?

The README does not provide a from-source build recipe for the whole repository. It directs users who simply want Keybase installed to monitor the releases page for macOS, Linux or Windows, and warns that a build from source might not do what it says it is doing.

### What programming languages does keybase/client use?

The core crypto libraries, the Keybase service and the command line client are written in Go, while the Android, iOS and desktop apps are built with React Native and Electron.

### Why does my keybase/client pull request show a failed Jenkins CI?

The README states that the project does not build external pull requests because it is a security risk to do so without a review first. If a Keybase team member reviews your PR, the commits are merged to a branch on the primary fork and built from there.

### Under what license is keybase/client released?

The README says most code is released under the New BSD (3 Clause) License, and that where subdirectories include a different license, that license applies instead.

### What is the docker-compose.yml in keybase/client for?

It defines development backend services named mysql.local, sqsd.local and kbweb.local, using images from a private Amazon ECR registry. The kbweb service sets KEYBASE_RUN_MODE=devel and exposes ports including 3000 and 9911.

## Sources

- [Issues](https://github.com/keybase/client/issues)
- [keybase/client on GitHub](https://github.com/keybase/client)
- [License: BSD-3-Clause](https://github.com/keybase/client/blob/master/LICENSE)
- [README](https://github.com/keybase/client/blob/master/README.md)
- [Releases](https://github.com/keybase/client/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/keybase-client