# Install Nucleus

Instructions for Claude, Codex, or another coding agent installing Nucleus for the current user.

## Current release

Install **0.4.0-alpha** for **Linux AMD64 or ARM64**, including Linux inside WSL2. This alpha includes secure pairing, NEXUS enrollment, signed telemetry, and explicitly opted-in hosted model work. A trusted local runtime and exact owner-approved artifact are separate requirements; neither this guide nor a subscription grants model approval. Preserve existing identity and settings.

Use a Linux/WSL2 terminal. The packaged binary does not require Go, Python, or a system service. If no supported Linux environment is available, report that requirement instead of installing another platform's package.

## Get the matching package

Run `uname -s` and `uname -m`. Use AMD64 for `Linux` / `x86_64`, or ARM64 for `Linux` / `aarch64` (also reported as `arm64`).

- [AMD64 archive](https://nucleus.parallax.link/downloads/nucleus/0.4.0-alpha/nucleus-0.4.0-alpha-linux-amd64.tar.gz)
- [ARM64 archive](https://nucleus.parallax.link/downloads/nucleus/0.4.0-alpha/nucleus-0.4.0-alpha-linux-arm64.tar.gz)
- [Release checksums](https://nucleus.parallax.link/downloads/nucleus/0.4.0-alpha/SHA256SUMS)

If the matching archive was supplied alongside this guide, use that local file. Otherwise the commands below download it from the release URL. A failed download or checksum is a stop condition; do not substitute another release or bypass verification.

## Verify and install for this user

Run the following in a scratch directory, or the directory containing the supplied archive. It installs into a versioned directory under `~/.local/share/nucleus/releases`. Set an absolute `NUCLEUS_INSTALL_DIR` first to choose another location.

The commands do not overwrite an existing release. If the destination already exists, inspect its `MANIFEST.json`, verify its `SHA256SUMS`, and run its `bin/nucleus help` before deciding whether installation is already complete.

```bash
set -eu

case "$(uname -s):$(uname -m)" in
  Linux:x86_64)
    nucleus_arch=amd64
    nucleus_sha256=be7925ef10d4fbeb7f7d8d356c6333f3f414fc241e524b0a75789ef8d185558f
    ;;
  Linux:aarch64|Linux:arm64)
    nucleus_arch=arm64
    nucleus_sha256=473ecbd653f6bb917375a352f4c205c50eaa25baf15be152bfa66c81e594fda9
    ;;
  *)
    printf '%s\n' 'This release requires Linux/WSL2 on AMD64 or ARM64.' >&2
    exit 1
    ;;
esac

nucleus_archive="nucleus-0.4.0-alpha-linux-$nucleus_arch.tar.gz"
if [ ! -f "$nucleus_archive" ]; then
  curl --fail --location --proto '=https' --tlsv1.2 \
    --output "$nucleus_archive" \
    "https://nucleus.parallax.link/downloads/nucleus/0.4.0-alpha/$nucleus_archive"
fi

printf '%s  %s\n' "$nucleus_sha256" "$nucleus_archive" | sha256sum --check -

nucleus_install_dir="${NUCLEUS_INSTALL_DIR:-$HOME/.local/share/nucleus/releases/0.4.0-alpha-$nucleus_arch}"
case "$nucleus_install_dir" in
  /*) ;;
  *) printf '%s\n' 'NUCLEUS_INSTALL_DIR must be an absolute path.' >&2; exit 1 ;;
esac
if [ -e "$nucleus_install_dir" ] || [ -L "$nucleus_install_dir" ]; then
  printf 'Release destination already exists: %s\n' "$nucleus_install_dir" >&2
  exit 1
fi

mkdir -p -- "$(dirname -- "$nucleus_install_dir")"
mkdir -- "$nucleus_install_dir"
tar -xzf "$nucleus_archive" -C "$nucleus_install_dir" --strip-components=1
(cd "$nucleus_install_dir" && sha256sum --check --quiet SHA256SUMS)
"$nucleus_install_dir/bin/nucleus" help
```

Report the absolute binary path and the verification result to the user. Use that binary directly; changing shell profiles, installing a global command, or starting a background service is not needed.

## Initialize and pair machines

Installation alone does not enroll this machine in a fabric. If the user also wants to initialize this node, run the installed binary with `init --name workstation`, choosing a recognizable name, then `identity` to inspect it. Preserve any existing Nucleus identity and membership.

For a second machine, follow the [pairing instructions](https://nucleus.parallax.link/downloads/nucleus/0.4.0-alpha/PAIRING.txt), also supplied alongside this guide. The owner issues an invitation; the joining machine returns a signed request; the owner checks and accepts it; the joining machine accepts the grant. Transfer those documents through a trusted channel. Do not choose a network endpoint, enroll another machine, or start a listener as part of merely installing the binary.

## Connect to the hosted organization

For hosted setup, use the installed binary:

```bash
"$nucleus_install_dir/bin/nucleus" cloud connect --url https://nucleus.parallax.link/dashboard
```

The CLI proves that this machine holds its existing private identity. It prints a verification URL, code, and full node fingerprint. Sign in through NEXUS, select the intended organization, compare the fingerprint, and approve the machine. An organization owner or admin must approve it, with an active Nucleus subscription and an available machine allowance. Private keys remain on the machine.

After approval, verify a real signed measurement:

```bash
"$nucleus_install_dir/bin/nucleus" cloud run --once
"$nucleus_install_dir/bin/nucleus" cloud status
```

Report whether the server acknowledged the measurement. A saved registration alone does not mean that the machine is online. For ongoing telemetry, `cloud run` stays in the foreground. If unattended monitoring is part of the requested setup, follow the [hosted setup guide](https://nucleus.parallax.link/downloads/nucleus/0.4.0-alpha/HOSTED.md) to configure a user service under the same account and NUCLEUS_HOME.

Organization administrators can revoke the machine in the [dashboard](https://nucleus.parallax.link/dashboard/machines). `cloud disconnect` sends a signed revocation and removes the local hosted binding; it preserves the machine's identity and private-fabric membership.


## Optional hosted CPU text work

Only do this when the user requested serving. Agent installation alone does not
authorize a runtime, model license, provenance exception, weight download, or
background service. Reuse approval already given in this session.

Linux/WSL2 and util-linux prlimit are required. The separately reviewed AMD64
llama.cpp CPU archive is build 12032, commit dde879bc4 (version 0.8.0-dev):

https://github.com/ggml-org/llama.cpp/releases/download/b12032/llama-b12032-bin-ubuntu-x64.tar.gz

Exact size: 22,886,629 bytes. SHA-256:
`9f10432ca3f66ef003a7a540aaffb9da0acadaefd05404521b9ab7a2436af304`

On Linux AMD64 only, download that archive, verify its exact SHA-256, and extract
into a new user-owned runtime directory. Preserve the complete layout and adjacent
shared libraries. Locate its regular executable llama-server and run --version.
Do not overwrite an existing installation. A failed download, checksum, platform,
instruction, library, or server-flag check is a stop condition. CPU execution uses
device none, zero GPU layers, and disabled operation/KV offload.

ARM64 Nucleus binaries are available, but no prebuilt ARM64 llama-server URL is
approved by this guide. Use a compatible trusted source build with a pinned
reviewed revision. Do not use the AMD64 archive on ARM64 or invent another URL.

Read the packaged inference/catalog/gemma-3-4b-it-text.json and its evidence.
This is public metadata and an example approval, not automatic permission.
The owner must explicitly accept Google's Gemma terms and the exact artifact
provenance exception. The disclosure stays incomplete/publisher-disclosed;
do not relabel it complete, change its hash, or weaken blocked-origin checks.
The dashboard separately requires model-license acceptance.

After that owner decision, create a new private FleetConfig from the public
catalog and the actual trusted runtime path. Record the owner's actual decision
in NUCLEUS_MODEL_REVIEW_NOTE; do not invent consent. Existing configurations must
be inspected/reused rather than overwritten. This script starts no process and
downloads no model:

```bash
export NUCLEUS_GEMMA_APPROVED=yes
export NUCLEUS_MODEL_REVIEW_NOTE='REPLACE_WITH_THE_ACTUAL_OWNER_DECISION'
nucleus_fleet_config="$HOME/.config/nucleus-hosted-runtime/fleet.json"
# Set nucleus_llama_binary to the actual absolute trusted llama-server path.
python3 - "$nucleus_install_dir/inference/catalog/gemma-3-4b-it-text.json" \
  "$nucleus_fleet_config" "$nucleus_llama_binary" <<'PY'
import json, os
from pathlib import Path
import sys
catalog_path, output, binary = map(Path, sys.argv[1:])
note = os.environ.get('NUCLEUS_MODEL_REVIEW_NOTE', '').strip()
if os.environ.get('NUCLEUS_GEMMA_APPROVED') != 'yes' or not note or note == 'REPLACE_WITH_THE_ACTUAL_OWNER_DECISION':
    raise SystemExit('Actual owner approval and Gemma terms acceptance are required')
if not output.is_absolute() or not binary.is_absolute() or not binary.is_file():
    raise SystemExit('Use absolute configuration and trusted runtime paths')
catalog = json.loads(catalog_path.read_text())
approval = catalog['example_owner_approval']
approval['review_note'] = note
if output.parent.resolve() != output.parent:
    raise SystemExit('Choose a configuration path without symlinked ancestors')
output.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
if output.parent.resolve() != output.parent or output.parent.is_symlink() or output.parent.stat().st_mode & 0o077:
    raise SystemExit('Choose a dedicated private configuration directory')
config = {'approved_models': [approval], 'runtime': {
    'binary': str(binary), 'threads': 2, 'context_length': 8192,
    'max_tokens': 256, 'memory_limit_bytes': 8589934592,
    'reserve_memory_bytes': 1073741824, 'startup_timeout_seconds': 120,
    'models': [],
}}
fd = os.open(output, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, 'w') as stream:
    json.dump(config, stream, indent=2)
    stream.write('\n')
print('Private configuration created; no model downloaded or started.')
PY
```

This is an 8 GiB process address-space budget,1 GiB host reserve, two threads,
context 8192 and a 256-token local cap. The model declares an 8 GiB requirement.
Admission requires enough effective available RAM after the reserve and enough
disk. These are limits, not measured RSS or a performance promise.

Use the same unprivileged account and NUCLEUS_HOME as enrollment. Choose a
dedicated private model directory:

```bash
"$nucleus_install_dir/bin/nucleus" cloud run \
  --inference "$nucleus_fleet_config" \
  --model-root "$HOME/.local/share/nucleus/hosted-models" \
  --allow-model-installs
```

The operator FleetConfig stays read-only. Managed models live in a private
hosted-models.json overlay inside the model root and reload on restart.
Operator-pinned entries cannot be removed by hosted jobs. A source configuration
change stops further work until restart. Without model flags no install/remove
is accepted; without --inference the agent sends telemetry alone.

In [Models](https://nucleus.parallax.link/dashboard/models), select the eligible
machine, review the exact model/license, and request installation. Wait for the
actual ready state before reporting success. Agent installation or a saved config
is not proof of downloaded or running weights. The worker permits only typed
signed outbound jobs, exact local approvals, pinned HF revisions, restricted
HTTPS redirects, verified hashes, and bounded memory/disk. It accepts no remote
shell or arbitrary executable/path. Lost/cancelled work is never rerun.

For unattended operation, adapt the same-user service in HOSTED.md with explicit
model flags and absolute paths. Stop the old worker before starting a replacement;
never copy private state into root or start a second worker under another user.

Manage organization context in [Context](https://nucleus.parallax.link/dashboard/context)
and use the actual scoped endpoint/key displayed in
[Connections](https://nucleus.parallax.link/dashboard/connections) for the client.
Never put keys, private profiles, prompts, or bearer headers in public reports.

The exact approved file passed offline policy, SHA-256, GGUF metadata and memory
preflight, followed by actual local context/schema generation for this
8192/256 profile with the stated 8 GiB/1 GiB budget and two CPU threads. One 32-token
request produced complete codename JSON, finish_reason=stop, and the matching
context document citation. This is local acceptance, not a production paid
request or a general throughput guarantee.

For a client requiring more context, inspect the actual advertised limits and
report its actionable context-limit error; do not silently weaken admission or
raise resource budgets.