# Get started with packages

> A guided path from "what is a package?" to safe releases: one registry for npm, PyPI, Cargo, Zig and containers, publishing and installing with your usual tools, mirrors that check every file, private packages, and advisories. Pictures first, every step explained.

Source: https://zaryn.xyz/docs/en/get-started-packages

Publish once, install by name, with the tools you already use. Zaryn is one registry for npm, PyPI, Cargo, Zig, containers and plain files, and a mirror for the public ones. Everything is on the [Packages](/packages) page.

## 1. What a package is

```diagram
type: flow
title: Publish once, install by name
---
Your code | A library, a tool, an app image | | 📦
~ npm publish, cargo publish, docker push…
Zaryn's registry | Stored by its hash, next to the repository that built it | accent | ▣
~ npm install, pip install, cargo add…
Anyone's project | One command, the same tool they already use | good | ✓
```

A **package** is code packed up so others can use it with one command. A **package manager** (npm, pip, cargo, zig, docker) installs it, and a **registry** is where it downloads from. Zaryn is a registry for all of them, so you only tell your tool where Zaryn is.

## 2. Five words you'll see

```diagram
type: cards
---
🔢 | Version | `1.4.2`. A published version never changes: a fix is `1.4.3` | accent
#️⃣ | Hash | A fingerprint of a file's bytes; your tool checks it on every install | good
🔗 | Dependency | A package your project uses; the package manager fetches it |
🔑 | Token | A password for tools: publishing needs one with `package:write` | warn
🙈 | Yank | Hide a broken version from new projects; existing ones keep working |
```

## 3. Why you can trust what you install

```diagram
type: graph
title: Three locks on every install
alt: A published version can't be replaced, every file is stored and checked by its hash, and a name that exists on Zaryn always comes from Zaryn, so a look-alike from a public registry can't sneak in
height: 36
---
node pub | published 1.4.2 | 12 18 | file | accent | Can never be replaced: the same bytes next year
node hash | its hash | 50 18 | hash | good | Stored under it; the installer checks it again
node you | your install | 88 18 | laptop | good | Gets exactly what was published
link pub hash | | path
link hash you | checked | path
```

Three things together: a version **can't be replaced**, every file is **checked by its hash** on the way in and out, and a name that exists on Zaryn **always comes from Zaryn**, so nobody can publish a same-named package on a public registry and slip it into your installs (*dependency confusion*).

## 4. Get a publish token

```diagram
type: flow
title: Once
---
Packages page | zaryn.xyz/packages | | ▣
~ Create a publish token
Token | Copy it now; it has `package:write` | warn | 🔑
~ give it to your tool
Ready | `.npmrc`, `~/.pypirc`, `cargo login`, `docker login` | good | ✓
```

Treat the token like a password: keep it out of public repositories (tools can read it from an environment variable), and make a new one if it leaks.

## 5. Pick your tool

```diagram
type: cards
title: The same idea, six tools
---
🟩 | npm | `@you` scope in `.npmrc`, then `npm publish --access public` | accent
🐍 | PyPI | `python -m build`, then `twine upload` to Zaryn's index |
🦀 | Cargo | `[registries.zaryn]` once, then `cargo publish --registry zaryn` |
⚡ | Zig | Upload the package; Zaryn gives the address and the hash `zig fetch` expects |
🐳 | Containers | `docker push zaryn.xyz/you/app:1.0` | good
📄 | Any file | `curl -T` to a fixed address: programs, datasets, firmware |
```

Each tool has its own guide with every step: [npm](/docs/en/packages-npm), [PyPI](/docs/en/packages-pypi), [Rust](/docs/en/packages-rust), [Zig](/docs/en/packages-zig), [containers](/docs/en/packages-containers), [files](/docs/en/packages-files).

## 6. Publish your first package

An npm package, start to finish:

```ini
# .npmrc in your project
@your-username:registry=https://api.zaryn.xyz/v1/packages/npm/
//api.zaryn.xyz/v1/packages/npm/:_authToken=${NPM_TOKEN}
```

```json
{ "name": "@your-username/hello", "version": "0.1.0", "main": "index.js" }
```

```bash
npm publish --access public
```

```diagram
type: graph
title: Only your scope goes to Zaryn
alt: npm sends @your-username packages to Zaryn and every other package to npmjs.com
height: 36
---
node npm | npm | 12 18 | laptop | accent | Reads .npmrc to decide where each package comes from
node z | Zaryn | 60 6 | cloud | good | `@your-username/…`
node pub | npmjs.com | 60 30 | cloud | | Everything else, as before
link npm z | @your-username/hello | path
link npm pub | react, lodash… | path2
```

To publish a fix, raise `version` and publish again. Without `--access public`, npm asks for a private package, which needs Premium.

## 7. Install it

```bash
npm install @your-username/hello          # npm, pnpm, yarn
pip install your-package                  # with Zaryn's index set once
cargo add your-crate --registry zaryn
docker pull zaryn.xyz/you/app:1.0
```

Your users set Zaryn up once, the same way you did, then install as usual. Public packages and images need no token to install.

## 8. Install straight from a repository

```diagram
type: flow
title: No publishing step
---
A commit | Any commit of a repository with a package.json, a pyproject or a build.zig.zon | | ⎇
~ the install tab
An address | A fixed archive of that exact commit | accent | 🔗
~ npm install …, pip install …
Pinned | Your project uses exactly that commit | good | 📌
```

The repository's **install** tab, next to the clone commands, gives the line for each tool. Good for trying a fix before it's released.

## 9. Faster installs through the mirrors

```diagram
type: graph
title: One command, every tool through Zaryn
alt: zev mirror on points pip, npm, go, cargo and rustup at Zaryn's mirrors, which check every file against its published hash
height: 40
---
node zev | zev mirror on | 12 20 | ci | accent | Adds a marked block to each tool's settings; `zev mirror off` removes it
node tools | pip, uv, npm, go, cargo, rustup, zig | 50 20 | laptop | |
node m | Zaryn's mirrors | 88 20 | cloud | good | Each file checked against the hash pypi.org, npm or crates.io lists
link zev tools | | path
link tools m | | path2
```

```bash
zev mirror on        # or pick some: zev mirror on pip cargo
```

Installing from pypi.org, npmjs.com, crates.io or GitHub slow, or blocked where you are? The mirrors fetch once and serve from Zaryn, and because every file is checked against a hash your tools already know, a mirror can't change anything. [Mirrors](/docs/en/package-mirrors).

## 10. Container images

```diagram
type: flow
title: From your laptop to a cluster
---
docker build | `zaryn.xyz/you/app:1.0`: registry, owner, image, tag | | 🛠
~ docker push
On Zaryn | Only layers Zaryn doesn't have are uploaded | accent | ⇡
~ docker pull, Kubernetes
Running | Public images need no login; private ones a read-only key | good | ▶
```

Helm charts and other OCI artifacts live next to images. Built by [CI](/docs/en/get-started-ci), an image also gets signed provenance and an SBOM.

## 11. Programs, datasets, firmware

```bash
curl -T mytool-1.0.0-linux.tar.gz -H "Authorization: Bearer $ZARYN_TOKEN" \
  https://api.zaryn.xyz/v1/packages/generic/mytool/1.0.0/mytool-1.0.0-linux.tar.gz
```

Anything that isn't a language package goes to a **fixed address**: name, version, file. Once uploaded, that address always gives the same bytes, and the answer includes the SHA-256 to publish next to the download.

## 12. Private packages, and space

```diagram
type: stats
---
500 MB | Free: packages and images | public packages; mirrors are free | 1 |
100 GB | Premium | private packages and images too | 100 | accent
0 | what others' packages cost you | installing public packages never counts | | good
```

On Premium, a package or image can be private: only you or your organization can see or install it, with the same token. [Plans](/docs/en/billing-and-credits).

## 13. When something you use is unsafe

```diagram
type: flow
title: An advisory reaches your project
---
Filed | An owner marks the affected commits: poisoned data, a backdoor, a wrong licence | bad | ⚠
~ lineage followed
You're told | Owners of everything built from them are notified, with a verdict | warn | 🔔
~ in CI
Blocked | `"advisories": {"fail_on": "high"}` stops a build on it | good | 🛡
```

Zaryn follows recorded lineage (trained on, fine-tuned from, derived from, uses), so an advisory reaches every repository built from the affected commits, and [CI](/docs/en/get-started-ci) can refuse to build while one reaches yours. [Advisories](/docs/en/advisories).

## 14. Names, versions, yanking

```diagram
type: cards
---
🏷 | Names | First come, first served, separately for each kind; only you publish new versions of yours | accent
🔢 | Versions | Never replaced: a fix is a new version |
🙈 | Yank | Hide a broken version from new installs; projects pinned to it keep working | warn
📦 | One place | All your packages and images, with their space, on the Packages page | good
```

Next: the guide for your tool, [Mirrors](/docs/en/package-mirrors) in depth, and [Advisories](/docs/en/advisories).