minters 0.3.2

money maketh man.

minters

money maketh man

minters is the packaged, local-first Mint distribution. It gives you the Seal terminal UI, a writable Mint workspace on your machine, the contract runner, the harness, the farm server, and the same repository structure the regulator expects when it reads, edits, validates, and runs contracts.

This README is written as a cookbook. Start at the quick start, then jump to the recipe that matches what you want to do.

quick start

Install or upgrade the package:

pip install --upgrade minters

Before you send your first prompt, make sure your local workspace or shell has a NINETH_API_KEY available. Seal uses Nineth for model requests, and without that key the UI can start but requests cannot run.

Example:

export NINETH_API_KEY=your_api_key_here
minters run

Launch the Seal UI:

minters run

minters run now opens a short setup wizard in the terminal before launching Seal. It lets the human configure the model API key and the broker flow for that workspace.

If you want to skip the wizard and launch with the saved workspace configuration, use:

minters run --default

On first launch, minters creates or reuses a writable Mint workspace, seeds it with the packaged project tree, and starts the interface defined in regulator/seal.py.

The packaged install is intentionally lean. It brings in the core dependencies needed for Seal and the local regulator runtime. Broker-specific tools stay optional and can be installed only when you need them.

recipe 1: choose where your workspace lives

By default, minters run resolves the workspace in this order:

1. --workspace /path/to/mint
2. MINTERS_WORKSPACE or MINT_WORKSPACE
3. the current directory if it already looks like a Mint workspace
4. ~/.local/share/minters/workspace

Use an explicit workspace when you want full control over where the model reads and writes files:

minters run --workspace ~/trading/mint

Ask minters which workspace it will use:

minters workspace

Or resolve a specific target without launching the UI:

minters workspace --workspace ~/trading/mint

If you want the model to operate on an existing checkout of this repository, open a shell in that checkout and run:

cd /path/to/mint
minters run

That keeps file edits, contracts, .env, and generated artifacts inside that same filesystem tree.

recipe 2: launch Seal with a specific model

Override the default regulator model for a single session:

minters run --model 1984-m3-0421

Or make it your default for all sessions:

export REGULATOR_MODEL=1984-m3-0421
minters run

recipe 3: understand what gets created on first launch

The first bootstrap copies the packaged Mint runtime into your workspace, including:

• contracts/ for strategy files
• harness/ for the contract runner and broker-facing APIs
• farm/ for the local MT5 Farm server
• regulator/ for the Seal UI and local service logic
• buildfile/, testsuite/, and the top-level project files

That means the model can inspect, create, modify, validate, and run contracts against the same workspace tree a human sees.

Your seeded workspace also gets a slim requirements.txt with the core runtime dependencies used by the packaged app. Install broker- or farm-specific extras only when your workflow needs them.

recipe 4: use the Seal interface day to day

Once Seal is open, type tasks directly into the prompt area and submit with Enter, Ctrl+Enter, or Ctrl+S.

Useful built-in examples:

inspect the contracts folder and summarize the strategies
fix the gold contract and iterate until it runs healthy
grep the repo for all uses of regulator and explain the flow
write a new contract in contracts/demo/contract.py and validate it

Useful local commands inside Seal:

/help
/clear
/model 1984-m3-0421

The feed shows:

• your prompt block
• tool calls such as reads, searches, file edits, and contract runs
• success or failure observations for each local service action
• the final model response

recipe 5: create a contract manually

Every runnable contract is just a Python file under contracts/ with a class whose name ends in Contract and an async def run(self) method.

Example:

import asyncio


class DemoContract:
    async def run(self) -> None:
        while True:
            print("demo heartbeat")
            await asyncio.sleep(5)

Save that as contracts/demo/contract.py, then ask Seal to validate or run it, or run it yourself from the workspace.

recipe 6: run contracts from the workspace shell

From inside your Mint workspace, you can run a single contract file directly:

python contracts/demo/contract.py

Or run the contract discovery loop that continuously scans contracts/ and restarts workers when files change:

python -m harness.bundler

The bundler injects MINT_WORKSPACE, and the runner loads your workspace .env before importing contract code.

recipe 7: use the default local farm backend

The default operating mode is the local farm-backed flow.

Start the Farm server from the workspace:

python -m farm.main

Expected endpoints:

• API: http://localhost:8000
• Controller: tcp://127.0.0.1:8888

Quick status check:

curl http://localhost:8000/farm/status

Use this mode when your machine is hosting or controlling MT5 instances locally.

recipe 8: switch to MetaAPI or farm_ext

Use the MetaAPI-backed external mode when you want cloud account access instead of the local farm:

export BROKER_MODE=farm_ext
export METAAPI_TOKEN=your_metaapi_token
export METAAPI_ACCOUNT_ID=your_metaapi_account_id

Then launch Seal or run your contracts as usual.

If you want Mint to choose automatically, use:

export BROKER_MODE=auto

recipe 9: switch to Capital.com

Enable the Capital backend:

export BROKER_MODE=capital

Or:

export CAPITAL_ENABLED=true

Set credentials in your workspace .env or shell:

CAPITAL_API_KEY=your_api_key_here
CAPITAL_IDENTIFIER=[e-mail]
CAPITAL_PASSWORD=your_password
CAPITAL_DEMO=true

If you need the Rust bridge locally, build it from the workspace:

cd harness/capital
maturin develop

Then start Seal again and let the model work against the Capital-enabled workspace.

recipe 10: keep secrets local

minters does not need your broker credentials baked into the package. Keep them in one of these places on your own machine:

1. a workspace-local .env
2. exported shell environment variables
3. platform-specific secret storage used by your local runtime

Typical knobs you may set locally include:

• NINETH_API_KEY
• BROKER_MODE
• METAAPI_TOKEN
• METAAPI_ACCOUNT_ID
• CAPITAL_API_KEY
• CAPITAL_IDENTIFIER
• CAPITAL_PASSWORD
• CAPITAL_DEMO
• REGULATOR_MODEL

recipe 11: upgrade minters safely

To get the latest package version:

pip install --upgrade minters

Your existing workspace is not wiped. minters only seeds files that are missing, so your contracts, edits, and .env stay local.

recipe 12: build and test the package locally

From the repository root:

python -m pytest testsuite/test_workspace.py -q
python -m build

Install the built wheel locally for a smoke test:

python -m pip install --force-reinstall --no-deps dist/minters-0.2.11-py3-none-any.whl
minters workspace --workspace /tmp/minters-smoke

recipe 13: troubleshoot the common cases

If Seal opens but edits land in the wrong place:

minters workspace

Then relaunch with an explicit path:

minters run --workspace /path/to/your/mint

If a contract cannot import the runtime, make sure you are running inside a real Mint workspace that contains harness/, contracts/, and regulator/.

If Seal starts but every prompt fails immediately, check the model credentials first:

echo "$NINETH_API_KEY"

If that is empty, add NINETH_API_KEY to your workspace .env or export it before launching minters run.

If you see a client-library compatibility error mentioning default_service, upgrade the runtime package or the Nineth client:

pip install --upgrade minters 'nineth>=0.5.16'

If Capital mode fails with an import error for the Rust bridge, rebuild it:

cd harness/capital
maturin develop

If farm mode is selected but no local server is reachable, start the farm process first:

python -m farm.main

If you want the model to work on this repository itself instead of a seeded copy, launch minters run from the repository root or set MINTERS_WORKSPACE to that path before starting Seal.