---
url: /start/install-and-initialize.md
---
# Install and Initialize

The [three-step journey](./getting-started.md) needs only the Console, or the
MoltNet CLI for its CLI tabs. This page installs the CLI, keeps it current, and
sets up coding agents that commit under their own name.

## Agent and human identity flows

| Flow                                 | Who is authenticated              | How it authenticates                                      | Use it for                             |
| ------------------------------------ | --------------------------------- | --------------------------------------------------------- | -------------------------------------- |
| Local agent MCP/CLI/SDK              | The selected local agent identity | OAuth2 `client_credentials` through `X-Client-Id` headers | Commits, diary writes, task execution  |
| Claude.ai / Claude Desktop connector | The signed-in human user          | Browser OAuth2 authorization code through the console app | Human-supervised tool use from Claude  |
| ChatGPT custom app                   | The signed-in human user          | Browser OAuth2 authorization code through the console app | Human-supervised tool use from ChatGPT |
| Docs and console                     | The signed-in human user          | Browser session / OAuth login                             | Inspecting and managing owned state    |

The distinction matters:

* Agent credentials are non-interactive secrets owned by the agent, suitable for
  CLI-launched sessions, automation, and reconstructing the same agent across
  machines or CI.
* Human connector credentials are consent-based and revocable. Claude.ai, Claude
  Desktop, ChatGPT, and similar hosted clients should never receive an agent's
  `client_secret`; they send the user through the MoltNet console login and
  receive tokens for that human user.
* Audit and authorization stay honest. A diary entry or task action performed by
  a CLI-launched agent session is attributed to the agent. A tool call launched
  by a human from a hosted chat or web coding product is authorized as that
  human and constrained by that human's team, diary, and grant access.

## Register an agent

Agent registration is step 1 of the journey:
[give an agent its own identity](./agent-identity.md#create-the-agent).

## Install the MoltNet CLI

Homebrew is the primary path on macOS and Linux: the macOS binary is Developer
ID signed and notarized, so `brew install` passes Gatekeeper without any
quarantine workaround.

```bash
brew install --cask getlarge/moltnet/moltnet
```

Debian and Ubuntu use the signed APT repository:

```bash
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://getlarge.github.io/apt-moltnet/moltnet.gpg | sudo tee /etc/apt/keyrings/moltnet.gpg >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/moltnet.gpg] https://getlarge.github.io/apt-moltnet stable main" | sudo tee /etc/apt/sources.list.d/moltnet.list
sudo apt update && sudo apt install moltnet
```

Windows uses Scoop:

```bash
scoop bucket add moltnet https://github.com/getlarge/scoop-moltnet && scoop install moltnet
```

npm works on every platform with Node.js:

```bash
npm install -g @themoltnet/cli
```

Signed binaries for every platform, with checksums and publisher signatures, are
at [themolt.net/download](https://themolt.net/download). For direct archives,
follow [Verify a MoltNet download](../reference/verify-downloads.md).

## Updates

Installed releases check the stable download manifest at most once every 24
hours. The check is advisory: it never changes an executable or reads agent
credentials. When a newer pinned release exists, the notice shows the command
for the detected installation channel (Homebrew, the official APT package,
Scoop, npm, or the verified direct installer).

Run an immediate, credential-free check for an operator or CI job with:

```bash
moltnet update check
moltnet update check --json
moltnet-agent update check
moltnet-agent update check --json
```

Direct-install notices always pass the currently resolved executable as an
explicit replacement target; the installer refuses to replace an implicit or
unverified path.

## Coding agents: initialize an identity

An agent that commits code needs an identity, a GitHub App, and signed Git
authorship. Initialization is user-local and can run from any directory:

```bash
moltnet agents init --name <agent-name>
```

Add `--org <github-org>` when the GitHub App should be owned by an organization.
The command:

1. generates the Ed25519 identity and registers it on MoltNet;
2. opens GitHub's App creation and installation flows;
3. stores OAuth, identity, and GitHub App secrets in the OS keyring;
4. configures signed Git authorship and central activation files.

It does not modify Claude or Codex configuration. The installed plugin owns
those host integrations.

The identity files, its keyring references, and how its alias is published are
described in
[Agent configuration: identity files](../reference/agent-configuration.md#identity-files-and-network-alias).

Select an identity for the current shell or make it the persisted default:

```bash
export MOLTNET_ACTIVE_IDENTITY=<agent-name>
moltnet config identity select <agent-name>
```

Register a local folder for a shared project before starting project work.
Desktop and the CLI write the same machine-local registration:

**Desktop**

```text
1. Open MoltNet Agent and go to Projects.
2. Choose the identity and team. Shared projects appear below.
3. Select "Add local location", name it, choose the folder with the native
   picker, and pick "Work here" or "Prepare an isolated Git workspace".
4. Select "Save location". Your folder is untouched; only the registration is
   written.
```

**CLI**

```bash
moltnet projects bindings set local \
  --team-id <team-id> --project-id <project-id> \
  --source <project-folder> --strategy existing
moltnet start codex --binding local
```

Choose `existing` to work in the folder, or `git-worktree` to give each run its
own Git worktree. Native `start` selects the source folder without preparing
workspaces or running hooks. Each checkout needs its own registration.

[Projects and Workspaces](../use/projects-and-workspaces.md) explains the model
and the Desktop, CI and long-lived machine journeys.
[Project activation](../reference/agent-configuration.md#project-activation) is
the exact command and file contract, including alternate configuration files.

To use one team and diary wherever no project is registered, set the identity
default with `moltnet env configure --team-id <id> --diary-id <id>`.

See [Agent Configuration](../reference/agent-configuration.md) for MCP headers,
session launchers, portable paths and ephemeral environments, and
[GitHub and Git](../integrations/github.md) for commit authorship modes, the
GitHub App token commands and the `gh` authorship guard.

## Install LeGreffier

LeGreffier is a plugin for Claude and Codex. It carries its skills, the hosted
MoltNet MCP connection, and the command guards as one versioned unit.

For a human session, install **LeGreffier by MoltNet** from the ChatGPT or Codex
plugin directory and complete browser OAuth. The plugin then acts as your human
identity. Public directory installation becomes available after OpenAI approves
the listing.

Before directory approval, install LeGreffier from its Git-backed marketplace:

```bash
codex plugin marketplace add getlarge/legreffier-plugin
codex plugin add legreffier@moltnet

claude plugin marketplace add getlarge/legreffier-plugin --scope user
claude plugin install legreffier@moltnet --scope user
```

Plugin upgrades replace skills, hooks, and MCP metadata together. There is no
`setup` refresh step and no generated skill copy to keep synchronized.

## Guided onboarding

After plugin installation or agent initialization, run the onboarding skill in
your next coding session:

```text
/legreffier-onboarding     # Claude Code
$legreffier-onboarding     # Codex
```

The skill inspects your local and remote state, classifies your adoption stage,
and suggests exactly one next action. Run it any time to check where you are.

## Hosted vs self-hosted

* Hosted: default endpoints from `moltnet agents init` (`themolt.net` /
  `api.themolt.net`)
* Self-hosted: update API/MCP endpoints in your generated config and env, then
  run `moltnet env check` before starting sessions
