Install HappyToken

Automatic setup gives OpenCode or Pi two DeepSeek models and HappyToken Vision through a local, authenticated router. Text-only requests go directly to DeepSeek with your key. Attach an image while either DeepSeek model is selected and the router sends that request to Vision using your HappyToken subscription.

Before you start

• macOS and Node.js 20 or newer
• OpenCode or Pi for automatic provider setup
• An active HappyToken subscription and API key
• A DeepSeek API key with API access

Subscription to first successful request

1. 1

   Subscribe

   Choose a plan and return to your account after checkout.

2. 2

   Create your HappyToken key

   In Account, choose New key. Copy the htk_… value into your password manager before closing it; the full value is shown once.

3. 3

   Prepare your DeepSeek key

   Create or retrieve a key in the DeepSeek platform. HappyToken keeps it on your Mac.

4. 4

   Install the router

   npm install --global happytoken-router

5. 5

   Save and validate both keys

   happytoken login

   Paste the HappyToken key first and the DeepSeek key second.

6. 6

   Configure one client

   happytoken setup opencode
   # or
   happytoken setup pi

   The command creates a timestamped client-config backup first.

7. 7

   Start and check the router

   happytoken start
   happytoken status

   Healthy output shows a running PID and ok for both upstreams. Status exits with code 1 when the PID, config or an upstream is unhealthy.

8. 8

   Select provider and model

   In OpenCode, run /models. In Pi, run /model. Choose provider happytoken and model deepseek-v4-flash.

9. 9

   Send the smoke prompt

   Reply with exactly: HAPPYTOKEN_TEXT_OK

   Success means the client returns that exact text and happytoken status remains healthy.

Verify vision

Keep happytoken/deepseek-v4-flash or happytoken/deepseek-v4-pro selected, attach an image and send:

Describe this image in one sentence.

The router automatically sends the image request to HappyToken Vision; selecting happytoken/happytoken-vision explicitly also works. A successful description and increased Vision usage in Account confirm the subscription path. The client must encode the image as a non-empty base64 data:image/...;base64,... URL. Remote HTTP(S) image URLs return 400 invalid_image_url before an upstream call.

Capability matrix

Another OpenAI Chat Completions client can use http://127.0.0.1:4280/v1 and your HappyToken key. Codex Responses and Claude Code Anthropic integrations require separate adapters.

Upgrade, revert and uninstall

Upgrade

happytoken stop
npm install --global happytoken-router@latest
happytoken setup opencode
happytoken start
happytoken status

Replace opencode with pi, or refresh both configured clients.

Revert a client config

happytoken setup opencode --revert
happytoken setup pi --revert

Run the command only for clients you configured. It restores only that client's latest backup; after repeated setup runs, that backup can already contain the provider. Use --remove when uninstalling.

Uninstall

happytoken setup opencode --remove
happytoken setup pi --remove
happytoken stop
npm uninstall --global happytoken-router

Run remove for every client you configured; it preserves other client settings, removes only the happytoken provider and backs up an existing client config first. Then stop the router and uninstall the package. The local ~/.config/happytoken/ directory remains for recovery; delete that exact directory manually only when you intend to permanently remove its keys, backups, logs and staged media.

Keys, backups and logs

• config.json stores both keys as local plaintext with file mode 0600 inside a 0700 directory.
• The DeepSeek key is sent only to DeepSeek. The selected client config contains the HappyToken bearer key.
• Repeated setup backups can contain a HappyToken key. Store recoverable key copies in a password manager and use encrypted device backups.
• Logs are router.out.log and router.err.log under ~/.config/happytoken/. Review them before sharing.

tail -n 100 ~/.config/happytoken/router.err.log

Error recovery

• Command missing: confirm Node.js 20+ and npm's global binary directory on your shell PATH, then open a new shell.
• Key rejected: confirm the HappyToken subscription/key and DeepSeek API access, then rerun happytoken login.
• Router stopped or upstream unreachable: run happytoken start, check status, then inspect the error log.
• Port 4280 busy: choose a free port in config.json, rerun setup for each client, then start.
• 402: renew or change the plan in Account.
• 429: the router performs limited retries; wait briefly before sending a new request if the limit continues.

Model IDs