minters 0.3.3

money maketh man.

minters

money maketh man

minters is now a remote-first Mint client.

The human machine gets a thin local install: the Seal terminal UI, the model connector, and the remote workspace client. The actual Mint workspace, repository CRUD, validation, contract execution, and shell sandboxing live on Modal.

The default deployed backend URL is:

https://weirdpablo--minter-api.modal.run

That URL is handled in code. A normal client does not need to set it manually.

This README is written as a cookbook. Start at the quick start, then jump to the recipe you need.

quick start

Install or upgrade the thin client:

pip install --upgrade minters

Launch Seal:

minters run

On first launch, Seal opens a short setup wizard. In the remote-first path it only asks for:

• your NINETH_API_KEY for model requests on the local machine
• the broker or harness credentials that should be synced into the remote Modal workspace

The client does not need a local copy of the Mint repository anymore.

If you want to skip the wizard and use the saved local settings immediately:

minters run --default

recipe 1: understand the new architecture

There are now two sides.

Client side:

• minters run
• the Textual Seal UI
• the Nineth client configuration
• the HTTP connector that talks to Modal

Server side on Modal:

• the writable Mint workspace volume
• repository file reads and writes
• grep, tree, and validation helpers
• contract execution
• short-lived shell sandboxes
• broker and harness runtime credentials

That means the model works against the server-side workspace instead of pushing the full source tree down to every client machine.

recipe 2: set credentials as a client

Run:

minters run

The wizard will:

1. ask for NINETH_API_KEY and store it locally so the UI can call the model
2. ask which remote credential profile you want to update
3. send those broker or harness credentials to the Modal workspace .env

Examples of values that may be synced to the remote workspace:

• FARM_HOST
• MASTER_ACCOUNT_ID
• METAAPI_TOKEN
• METAAPI_ACCOUNT_ID
• CAPITAL_API_KEY
• CAPITAL_IDENTIFIER
• CAPITAL_PASSWORD
• CAPITAL_DEMO

recipe 3: see where Seal is running

Inside Seal, use:

/target

That prints the active target. In the normal packaged flow it should point at the deployed Modal workspace, not the local machine.

Useful interactive commands:

/help
/clear
/model 1984-m3-0421
/target

recipe 4: keep the client machine thin

The packaged client no longer bootstraps the full repository into the user workspace by default.

The default workspace path is still used for local config files:

minters workspace

But the repository itself stays on Modal unless a maintainer explicitly forces local development mode.

recipe 5: force local mode for development

If you are working inside this repository and want the old local execution path for debugging, use:

minters run --local

Or:

export MINTERS_FORCE_LOCAL=true
minters run

If you also want the old local workspace tree to be copied into a target directory, opt in explicitly:

export MINTERS_ENABLE_LOCAL_WORKSPACE_BOOTSTRAP=true
minters run --local --workspace /tmp/mint-local

That path is for maintainers and local debugging, not for normal client installs.

recipe 6: deploy the backend to Modal

From the repository root:

modal deploy entry.py

The deployed web endpoint is created from entry.py, which serves the Modal-backed FastAPI app. The backend mounts the named Modal volume minter, keeps the workspace under /data/minter/workspace, and runs command or contract execution in short-lived Modal sandboxes.

The deployment output includes the public URL. In the current deployment it is:

https://weirdpablo--minter-api.modal.run

That value is baked into the client connector as the default remote URL.

recipe 7: smoke test the deployed backend

After deployment, run:

python buildfile/modal_smoke.py --url https://weirdpablo--minter-api.modal.run

The smoke script checks:

• /modal/health
• /modal/workspace/info
• remote read_file
• remote write_file
• remote sandbox_run

The CI pipeline now runs that same smoke step after modal deploy entry.py.

recipe 8: understand what ships to PyPI

The PyPI package is now intentionally thin.

It ships:

• minters
• the client-facing regulator modules used by Seal
• the remote connector

It does not ship the full repository runtime to end users by default.

That means the client wheel no longer bundles:

• harness/
• farm/
• contracts/
• testsuite/
• the Modal server module used only by deployment
• the old native Capital wheel payload in the client package

recipe 9: understand CI/CD now

The release workflow now does four things:

1. bumps and tags the version when the commit message starts with build:, feat:, or chore:
2. builds the thin client wheel once
3. verifies client install on Linux, macOS, and Windows
4. deploys the Modal backend, parses the deployed URL, and runs the live smoke script

That gives you a thin cross-platform client plus a single deployed backend runtime.

recipe 10: troubleshoot the common cases

If Seal starts but cannot reach the backend, check the deployed service URL first:

python - <<'PY'
from regulator.remote import remote_url
print(remote_url())
PY

If the wizard fails while syncing broker credentials, the Modal deployment is reachable but the remote workspace API rejected the write. Redeploy the backend and rerun:

modal deploy entry.py
python buildfile/modal_smoke.py --url https://weirdpablo--minter-api.modal.run

If you intentionally need the old local path, use minters run --local.

If model requests fail immediately, verify the local model credential:

echo "$NINETH_API_KEY"

If that is empty, add NINETH_API_KEY locally and rerun minters run.