mint

Documentation

Run Mint in an afternoon

This page is the operator quickstart. The authoritative contracts live in the repository and are linked below; where this page and the repository disagree, the repository wins.

Read this before deploying

Mint does not authorize requests. Any caller that can reach the service can choose any HTTP(S) destination and use any alias, including to exfiltrate a credential. Tailscale reachability and host custody are the only boundary. The full threat model is in VISION.md.

Quickstart

One host, one file, one service

You need a dedicated Linux host joined to your Tailscale network. Agents do not run on this host, and the Mint port must be reachable only from your tailnet.

1. Create the secret file

Over trusted Tailscale SSH custody, create /etc/mint/secrets.env with one alias=value record per line. The file must be owned by the mint service account, mode 0600, and at most 64 KiB. Real values never enter Git, logs, or agent-readable paths. 

# /etc/mint/secrets.env — live values stay on this host
vendor.default=<provider key pasted by the operator>

2. Configure the service

Create root-owned /etc/mint/mint.env. The bind address must be the host's explicit Tailscale address — never a wildcard or unspecified address. 

MINT_BIND_ADDR=100.64.0.10:4949
MINT_SECRET_FILE=/etc/mint/secrets.env

3. Build and install

cargo build --release --locked
sudo install -o root -g root -m 0755 target/release/mint /usr/local/bin/mint
sudo install -o root -g root -m 0644 deploy/mint.service /etc/systemd/system/mint.service
sudo systemctl daemon-reload
sudo systemctl enable mint
sudo systemctl restart mint

4. Verify liveness

From any device allowed on the tailnet:

curl --fail http://100.64.0.10:4949/healthz
# ok

5. Call a provider through the proxy

Agents address any HTTP(S) destination through the single proxy route and put a marker where the credential belongs. Mint substitutes from the startup map and streams the exchange. 

curl http://100.64.0.10:4949/proxy/https/api.example.com/v1/models \
  -H "Authorization: Bearer __mint.vendor.default__"

To rotate a credential, edit the secret file under trusted custody and run systemctl restart mint. There is no reload signal and no fallback path.

Canonical contracts

Authoritative references