Rust and Cargo
A hub as a Cargo registry: setup, publishing crates, depending on them
You write Rust, your team has crates it does not want on crates.io, and you
would like cargo add, cargo build and Cargo.lock to keep working exactly
as they do today. This chapter makes your hub one more registry Cargo knows
about, next to crates.io. Cargo keeps doing everything it already does; the hub
becomes another place a crate can come from.
Maturity: Available. The hub serves a Cargo sparse registry: setup,
diagnosis, publishing, resolution, download, yank and search work with
ordinary Cargo. cargo owner is not supported; ownership is managed by the
hub (see Names, scopes and owners).
What you will be able to do
- add your hub to a Cargo project as a named registry, with one command;
- check that Cargo, your login and the registry agree, with one command;
- publish a crate to the hub, all or nothing, with a receipt;
- depend on a private crate and a crates.io crate in the same
Cargo.toml; - yank a bad version with
cargo yank.
You need a login on the hub first. If gritpack auth status does not show your
account yet, read Logging in and come back.
What does not change
Cargo is still the resolver, the builder, the test runner and the owner of
Cargo.lock. cargo build, cargo test, rust-analyzer and your CI do not
change. crates.io stays Cargo's default registry: only dependencies that name
the hub's registry come from the hub.
The hub never runs cargo, rustc, build scripts or macros. It does not
mirror crates.io, and it does not change how Cargo resolves. It gives crates a
place to live, an owner, a search entry and signed evidence of who published
them.
From Cargo. A Gritpack hub is an alternate registry in Cargo's own sense: a
[registries.<name>]entry with a sparse index, andregistry = "<name>"on each dependency that should come from it. Crate names stay ordinary Cargo names. Gritpack's@scope/nameform is not used for crates.
1. Point Cargo at the hub
From the directory of a Cargo project, run:
$ gritpack setup
setup adapter=cargo profile=work status=changed registry=gritpack config=./.cargo/config.toml
Gritpack saw Cargo.toml, asked your hub where its Cargo index is, and wrote
one registry entry into the project's own .cargo/config.toml:
[registries]
[registries.gritpack]
index = "sparse+https://packages.example.com:7446/cargo/index/"
credential-provider = ["/home/you/.frogfish/gritpack/bin/gritpack", "cargo-credential", "--profile", "work", "--config", "/home/you/.frogfish/gritpack/config.toml"]
Two things to notice:
- The registry is called
gritpackunless you choose another name with--cargo-registry, for examplegritpack setup --cargo-registry company. That name is what yourCargo.tomlfiles will say. - No token is stored. The
credential-providerline tells Cargo to ask Gritpack whenever it needs to authenticate. Gritpack uses your login to get a short-lived token for that one operation, and Cargo never writes it to its credentials file.
Run it again and nothing changes:
$ gritpack setup
setup adapter=cargo profile=work status=unchanged registry=gritpack config=./.cargo/config.toml
setup uses your default login. To use another, pass --profile work. If the
directory holds more than one kind of project, for example a Cargo.toml and
a package.json, Gritpack does not guess: choose with --adapter cargo.
Commit .cargo/config.toml if everyone on the team uses the same hub and the
same profile name, or keep it out of version control and let each person run
gritpack setup once. The paths in it are absolute paths on your machine.
Cargo must trust the hub's certificate
When your hub uses a certificate from a public certificate authority, there is nothing to do. When your hub's administrator gave you a certificate authority file of your own, Cargo needs it too, because Cargo makes its own HTTPS connections. Either install it in your operating system's trust store, or tell Cargo where it is:
[http]
cainfo = "/home/you/.frogfish/gritpack/hub-ca.pem"
You can put that in the same .cargo/config.toml, or set the
CARGO_HTTP_CAINFO environment variable.
Setting up a registry for every project at once
gritpack setup writes to one project. To add the hub to your user-wide Cargo
configuration instead, use gritpack cargo setup and say which name and login
to use:
$ gritpack cargo setup --registry company --profile work --index sparse+https://packages.example.com:7446/cargo/index/
configured Cargo registry company profile=work index=sparse+https://packages.example.com:7446/cargo/index/ config=/home/you/.cargo/config.toml
It changes only [registries.company] and leaves the rest of the file,
comments included, alone. Running it again reports verified instead of
configured. If an entry with that name already exists and differs, it stops
and asks you to look, or to pass --force:
$ gritpack cargo setup --registry company --profile work --index sparse+https://other.example/cargo/index/
invalid Cargo registry configuration: registry "company" already differs; inspect /home/you/.cargo/config.toml or rerun with --force
Without --index, gritpack cargo setup assumes the index is on port 7446 of
your login's hub. gritpack setup asks the hub instead, so prefer it, or pass
the --index your administrator gave you. --cargo-config writes a different
Cargo configuration file.
Careful. Cargo reads every
.cargo/config.tomlfrom the current directory up to your home directory, and the one nearest the project wins. If your home directory's Cargo configuration already defines a registry calledgritpack, a command run outside the project (for example with--manifest-path) uses that one. Run Cargo from inside the project, or pick a distinct name with--cargo-registry.
2. Check it
One command checks the Cargo configuration entry, your login, the token, TLS and the sparse index:
$ gritpack cargo doctor --registry gritpack --cargo-config .cargo/config.toml
healthy Cargo registry gritpack profile=work index=sparse+https://packages.example.com:7446/cargo/index/ cargo=cargo 1.98.1 (797e8a9bc 2026-08-05) token_expires_at=1794900709
token_expires_at is when the token minted for the check stops working, in
Unix seconds: five minutes later. Tokens are made fresh for each operation, so
nothing long-lived sits on disk.
When something is wrong, the doctor says what and exits with a non-zero code. For example, an index address that does not answer:
$ gritpack cargo doctor --registry company
cannot reach the hub: error sending request for url (https://packages.example.com:7446/cargo/index/config.json): client error (Connect): tcp connect error: Connection refused (os error 111)
That one exits with code 8, "unavailable" (see
Scripting with JSON for all exit codes). Add
--json for a structured report:
{
"cargo_version": "cargo 1.98.1 (797e8a9bc 2026-08-05)",
"index": "sparse+https://packages.example.com:7446/cargo/index/",
"profile": "work",
"registry": "company",
"token_expires_at": 1794900787,
"warnings": []
}
gritpack doctor in the project directory runs the general checks too: your
login, your account, the hub, and then the Cargo routing.
$ gritpack doctor
PASS project — detected cargo at ./
PASS profile — profile=work provider=file
PASS provider — credential material resolved
PASS identity — account=01a1e866-2c84-77b1-a23c-6ca9f59543bf email=ada@example.com status=Active
PASS hub — repository=550e8400-e29b-41d4-a716-446655440000 endpoint=https://packages.example.com:443
PASS ecosystem — cargo=cargo 1.98.1 (797e8a9bc 2026-08-05) index=sparse+https://packages.example.com:7446/cargo/index/
3. Publish a crate
Crates keep their ordinary Cargo names. In the crate's Cargo.toml, name the
registry in publish, so a stray cargo publish can never send the crate to
crates.io:
[package]
name = "ada-strings"
version = "0.1.0"
edition = "2021"
description = "Small string helpers"
license = "MIT"
readme = "README.md"
publish = ["gritpack"]
Every new version on a hub needs a README of at least 100 words and a licence
declaration (license or license-file). README and licence
explains the rule and how to go without one when you must.
Now ask Gritpack to check everything without publishing:
$ gritpack publish --dry-run
planning publication; Cargo members may run cargo metadata/package and rustc version checks
publication plan=sha256:677065b0... result=RequiresRemoteVerification nodes=1 edges=0 output=./.gritpack/publication-plan.json
cargo:ada-strings@0.1.0 adapter=Cargo status=Indeterminate artifact=.gritpack/publication/artifacts/cargo-ada-strings-0.1.0.crate
check=CARGO_VERSION_RECORDED status=Passed — cargo 1.98.1 (797e8a9bc 2026-08-05)
check=RUSTC_VERSION_RECORDED status=Passed — rustc 1.98.1 (48a229cea 2026-09-01)
check=CARGO_PACKAGE_CONSTRUCTED status=Passed — Cargo produced a normalized archive containing 5 files
check=CARGO_DESTINATION_PERMITTED status=Passed — Cargo package.publish permits registry gritpack
check=PUBLICATION_METADATA_INCOMPLETE status=Warning — Cargo.toml does not declare repository; catalogue pages and search will show this version without it, and a published version cannot be amended
check=CARGO_PACKAGE_VERIFIED status=Passed — Cargo completed native package verification
check=PUBLICATION_DOCUMENTATION_POLICY status=Passed — README and licence meet the hub's documentation policy
check=PUBLICATION_LICENSE_DECLARED status=Passed — MIT
publication verification plan=sha256:677065b0... repository=550e8400-e29b-41d4-a716-446655440000 result=Publishable generation=sha256:fe5bcb83...
cargo:ada-strings@0.1.0: New
dry run complete; registry was not mutated
Read it from the top. Gritpack asked Cargo to package the crate (cargo package, so Cargo builds and verifies it exactly as cargo publish would),
recorded the Cargo and Rust versions, checked that publish allows this
registry, checked the README and licence, and then asked the hub whether the
version may be published. New means the hub does not have this version yet
and you own the name. The warning is advice: a repository field would make
the crate's page more useful, and a published version can never be amended.
When the dry run is clean, publish:
$ gritpack publish
...
committed publication transaction=01a1e866-ed1f-7bd3-96c9-8a928750e562 plan=sha256:677065b0... nodes=1
cargo:ada-strings@0.1.0: New storage_id=cargo-sha256:3e1a4d2d... digest=sha256:3e1a4d2d...
On a terminal, publish shows the plan and asks before it changes anything.
In a script or CI job, pass --yes.
What happened: Gritpack normalised Cargo's .crate file so the same source
always gives the same bytes, uploaded it, and the hub checked it again on its
own side and made it visible in one step. Either the whole publication is
visible or none of it is. The hub keeps a signed receipt you can fetch later
(Evidence and receipts). Running the same
command again for the same version does not publish twice; Gritpack finds the
finished publication and reports it.
The crate is now on the hub:
$ gritpack info ada-strings
ada-strings 0.1.0 (cargo)
Small string helpers
dialect: rust/cargo
versions: 0.1.0
license: MIT
owner: 01a1e866-2c84-77b1-a23c-6ca9f59543bf
crate sha256: 3e1a4d2d54e0cfbd97659bdb81766f5b17c7b3f0f30e53d62719eec5d3580e6f
use: cargo add ada-strings@0.1.0 --registry <registry>
The first account to publish a crate name owns it. Another account trying to
publish ada-strings is stopped at the dry run with
PUBLICATION_AUTHORITY_DENIED: publisher does not own the Cargo package name.
When the registry has another name
gritpack publish assumes the registry is called gritpack. If your
Cargo.toml says publish = ["company"], tell it so; otherwise Cargo refuses
to package the crate:
gritpack publish --cargo-registry company
In a Cargo workspace with several crates, gritpack publish plans them all
together and publishes them all or none, in dependency order. --package NAME
(repeatable) limits it to some of them. Uncommitted changes are refused, as
Cargo refuses them; --allow-dirty lets them through.
Publishing step by step covers plans and
transactions in depth.
What about plain cargo publish?
cargo publish --registry gritpack talks to the same registry. Whether the hub
accepts it depends on the hub. A hub that keeps signed evidence for every
publication accepts new versions only through Gritpack's transactional
publication, and answers plain cargo publish like this:
error: failed to publish ada-strings v0.1.1 to registry at https://packages.example.com:7446/cargo
Caused by:
the remote server responded with an error (status 409 Conflict): repository evidence policy requires gritpack transactional publication
Then use gritpack publish. It runs Cargo's own packaging and verification
for you, so you lose nothing.
4. Depend on a private crate
In a project that should use the crate, run gritpack setup once, then use
Cargo as usual:
$ gritpack setup
setup adapter=cargo profile=work status=changed registry=gritpack config=./.cargo/config.toml
$ cargo add ada-strings --registry gritpack
Updating `gritpack` index
Adding ada-strings v0.1.1 to dependencies
$ cargo add itoa@1
Adding itoa v1.0.19
Cargo.toml now holds one dependency from the hub and one from crates.io:
[dependencies]
ada-strings = { version = "0.1.1", registry = "gritpack" }
itoa = "1"
$ cargo run -q
HELLO!
Both crates resolved into one graph, and Cargo.lock records where the
private one came from:
[[package]]
name = "ada-strings"
version = "0.1.1"
source = "sparse+https://packages.example.com:7446/cargo/index/"
checksum = "b1cd6213cb6cc9395de8d6a779dcc50ed3a963dfc0ce7c9b2a6965d3de4f57fa"
Commit Cargo.lock as you always would. A dependency without registry = ...
never comes from the hub, and a private crate never silently comes from
crates.io, so a crates.io crate with the same name cannot take its place.
For automation. In CI, the job needs a Gritpack login (see Continuous integration), the same
.cargo/config.tomlentry, and the hub's certificate authority if it has a private one. Thencargo build --lockedworks as usual.
5. Find, yank and look after crates
Search works from Cargo or from Gritpack:
$ cargo search ada --registry gritpack
ada-strings = "0.1.1" # Small string helpers
$ gritpack search strings
ada-strings 0.1.0 ecosystem=cargo score=250 dialect=rust/cargo variants=1 — Small string helpers
gritpack search and gritpack info show native packages and crates in one
list; --ecosystem cargo shows only crates. gritpack info ada-strings --ecosystem cargo --json gives the full record, README included.
A published version never changes. If 0.1.0 has a bug, publish 0.1.1. To
stop new projects from choosing a bad version, yank it with Cargo:
$ cargo yank ada-strings@0.1.1 --registry gritpack
Updating `gritpack` index
Yank ada-strings@0.1.1
$ cargo yank --undo ada-strings@0.1.1 --registry gritpack
Updating `gritpack` index
Unyank ada-strings@0.1.1
A yanked version stays downloadable for projects whose Cargo.lock already
names it; Cargo just stops choosing it for new resolutions. For crates, use
cargo yank: gritpack package yank and gritpack package deprecate work on
native packages, and answer "package not found" for a crate.
Things Cargo can ask that the hub does not answer yet:
cargo ownerreports "requested operation not supported". Crate names are owned by the account that first published them; an administrator can see and change ownership.- There are no per-crate access lists. Everyone with a login on a private hub can read every crate on it; the hub itself is the privacy boundary.
When something looks wrong
| You see | It usually means |
|---|---|
no matching package named ... found from Cargo | the dependency lacks registry = "gritpack", or the registry name in Cargo.toml differs from the one in .cargo/config.toml |
| an SSL or certificate error from Cargo | Cargo does not trust the hub's certificate authority; set http.cainfo |
cannot be packaged during gritpack publish | publish = [...] names another registry; pass --cargo-registry |
PUBLICATION_DOCUMENTATION_REQUIRED | the crate has no README of 100 words, or no licence; see README and licence |
repository evidence policy requires gritpack transactional publication | publish with gritpack publish instead of cargo publish |
Troubleshooting by symptom has more.
What just happened
- One command put your hub next to crates.io in the project's Cargo configuration, with no token stored anywhere.
gritpack publishhad Cargo package and verify the crate, then published it to the hub in one step, with a signed receipt.- A second project depended on the private crate and a crates.io crate in one
Cargo.toml, andCargo.lockrecorded where each came from. - Cargo stayed in charge of resolving, building and locking throughout.
You can stop here
A Rust team that wanted private crates without changing how it builds is done. Your CI needs a login too; Continuous integration shows how.
Next
- The npm, Go and C/C++ chapters cover the same ground for those languages: npm, Go modules, C and C++.
- Optional deep dive: Releasing a workspace for several crates (and packages in other languages) published together, all or none.