asm

A home for assembly.

Asm is a package registry and command-line tool for assembly projects.
Create and test projects, inspect packages, and download exact artifacts.

Website · Quick start · Status · Why Asm · Security model · Sponsor Asm

Packages declare their targets and connect release records to exact source and artifact digests.
The project purpose explains our technical assumptions about AI-assisted assembly.

Quick start

Asm 0.6.0 supports Linux x86-64, Linux ARM64, and Apple Silicon with macOS 15 or later.

Install the command

Install GitHub CLI 2.93.0 or later before running the installer.

curl -qfsS -m120 https://asm.build/install.sh | sh

Apply the PATH command shown by the installer.
Then check the version:

asm version

On Apple Silicon, the output is asm 0.6.0 (aarch64-macos).

export PATH="$HOME/.local/bin:$PATH"

Add this command to your shell configuration to keep the setting.

Installer source · Installation requirements · macOS filesystem and signing requirements

Run your first project

Install GNU Binutils on Linux, or Xcode Command Line Tools on macOS with xcode-select --install.
On Debian or Ubuntu, the binutils package supplies the assembler and linker.

Run these commands from the directory that will contain your new project:

asm doctor &&
asm new hello &&
cd hello &&
asm run &&
asm test

The program prints:

Hello from asm!

The project contains asm.toml, src/main.s, and tests/main.s.
Assembly source is text; asm build assembles and links it into the executable build/app.
asm run also runs that executable.
asm test builds and runs tests/main.s; a zero exit code passes the test.

Update Asm

For an installation made with the installer:

asm self update

For an installation managed by another package manager, use that manager to update Asm.

Projects and packages

Describe a project

asm.toml names the project, its source file, and its target:

[package]
name = "hello"
version = "0.1.0"

[build]
source = "src/main.s"
target = "x86_64-linux"

asm new sets the target for your machine.
Linux ARM64 uses aarch64-linux; Apple Silicon macOS uses aarch64-macos.

Asm 0.6.0 also accepts one project with several [target.<id>] implementations.
Each target has its own source, test, and optional native-library fields.
The hello and math projects keep these inputs under targets/<id>/.
asm build --target riscv64-linux builds a separate Linux artifact.
asm test --target riscv64-linux --no-run builds its test without executing it.
Target-specific dependency selections share one v2 lock.
See the multi-target project contract for tools, commands, and platform limits.

Find a package

asm search hello
asm info stubbi/hello
asm versions stubbi/hello
asm fetch stubbi/[email protected] --target x86_64-linux --kind source

This downloads the Linux x86-64 source archive and checks its size and SHA-256 digest.
Use asm --help for command options.

Use a source dependency

This example requires Linux x86-64 and gzip at /usr/bin/gzip.
From a project directory:

asm add stubbi/[email protected] --target x86_64-linux
asm lock

Include the library in your source:

.include "stubbi/math/0.6.0/x86_64-linux/targets/x86_64-linux/src/min.s"

The complete example calls asm_u64_min and explains its calling convention.

Commit asm.lock with your project.
asm sync restores the recorded dependencies.
asm build --locked requires the lock file and checks dependencies before assembly.

Install a program

On Linux x86-64 or ARM64:

asm install stubbi/[email protected]

This installs the matching executable at $HOME/.local/bin/hello.
Use --output PATH to choose another destination.
The destination must be a new file.
Asm records both default and custom destinations in its local inventory.
One package identity has at most one managed installation.

Inspect and manage recorded programs:

asm installed
asm upgrade stubbi/hello
asm uninstall stubbi/hello

upgrade selects the highest available host version from the recorded registry.
Use owner/name@version to select an exact version.
update and remove continue to manage project source dependencies.

Published 0.4.0 binaries do not include these management commands.
Updating Asm does not adopt earlier installations; programs without an inventory record remain unmanaged.
See the installed-program contract for file checks, recovery, and limits.

Status

Asm is an early alpha.

Asm 0.6.0 adds named target implementations, standalone Linux cross builds, and target-specific dependency locks.
The release notes describe the commands, artifact scope, and limits.

Projects select the native host by default.
Explicit standalone Linux builds produce separate artifacts without executing them.
Cross-target native-library linking remains unsupported.
Packages can provide separate artifacts for other targets, including RISC-V Linux.

Transitive dependencies, self-service publication, account recovery, isolated public build workers, and hosted formal verification are planned.
The roadmap tracks that work.

Prepare a release record

A package release records its source repository, exact Git commit, target, and artifact digests.
asm publish checks the release files and prepares a local release record.
It makes no network request and publishes nothing.
The hosted operator can import accepted catalog snapshots.
Public publisher authentication and hosted deployment remain unqualified.

Use the packaging and compatibility guide to prepare artifacts and records.
The hosted publication boundary states the remaining requirements.

Build with an AI

The Asm development skill guides requirements, target selection, package reuse, tests, and bounded performance work.
The MCP setup guide connects AI clients to read-only discovery, planning, and measurement-comparison tools.
The AI uses its authorized workspace tools to build and execute software.

Hosted registry and MCP deployment remain under qualification.
The hosted registry contract records the implementation scope and remaining recovery, security, and runtime gates.

Security evidence

Package records distinguish artifact checks, build provenance, formal proofs, and agent reviews.
Each result applies to a particular check and artifact.
Missing results appear as missing.

The security model explains the checks, trust boundaries, and planned verification services.

Build from source

Install Git, Make, and Python 3.11 or later.
Linux also requires GNU Binutils, curl, GNU Coreutils, and gzip.
Apple Silicon macOS requires Xcode Command Line Tools.

git clone https://github.com/stubbi/asm.git &&
cd asm &&
make &&
make install PREFIX="$HOME/.local" &&
export PATH="$HOME/.local/bin:$PATH" &&
asm version

make selects the native implementation for your machine.
It runs the assembler and linker to create the executable.
It also provides test and installation commands.
The root asm.toml describes the Linux x86-64 reference build.
The CLI source guide explains the layout and installation helper.
The ARM64 notes cover cross-assembly; the macOS guide covers Apple Silicon builds.

Support Asm

Help fund maintainer time, registry operations, security work, and documentation.
The sponsorship page lists company and individual options, recognition, and terms.
Sponsorships are arranged by email.
Confirm availability and payment details before you pay.

Contribute

Start with CONTRIBUTING.md and AGENTS.md.
The repository layout explains the source, licenses, experiments, and retained measurements.
Follow the design guide, writing guide, and code of conduct.

The CLI uses assembly for project and package logic, with system tools for assembly, linking, transport, and cryptographic checks.
Python handles registry operations, release automation, and the separate MCP protocol adapter; JavaScript supports the website.
The hosted registry runtime foundation uses assembly with mature protocol and database libraries.
The bundled-verifier migration uses Go for the Sigstore and TUF adapter.

On Linux, run make check from the repository root.
On macOS, run make test.
The contribution guide lists test prerequisites, including cross-toolchains.
Include the reason for your change and its validation in the pull request.
Report defects through GitHub Issues.

License

Copyright (c) 2026 ASM contributors.

Unless a file has a separate notice, Asm uses AGPL-3.0-or-later.
You can use version 3 or a later version published by the Free Software Foundation.
Asm is provided without warranty.

Starter assembly files contain the complete MIT notice.
The same notice remains in examples/hello/LICENSE and examples/math/LICENSE.
It covers the identified MIT material and preserves the notice for material originally distributed in Asm 0.1.0.

Running Asm does not assign its license to a separate program.
Copied or linked package code has its own license conditions.
Contributions use the license that applies to the affected material.
Keep required copyright and permission notices.

Asm 0.1.0 was published under MIT.
Asm 0.2.0 introduced AGPL-3.0-or-later for the platform.
Earlier releases retain their original bytes and licenses.
Run asm license for the identifier, source location, and warranty notice.