Get started with 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).