SOLWYN

Set up Solwyn with your coding agent

Paste one prompt into Claude Code, Codex or Cursor. Your agent runs every command. You only open links in your browser to sign up, verify your email and approve.

You paste one prompt into your coding agent, and it does the setup. It installs the Solwyn CLI, logs in, creates a project with a hard cap named after your repository, writes .solwyn.env and Solwyn's agent guidance into your repository, adds the Solwyn MCP server to its own configuration, wraps your LLM provider clients with the SDK and makes a test call.

You don't type anything in a terminal. You open links in your browser: to sign up or sign in, verify your email, approve the login and approve the new project.

What you need

  • Python 3.11 or newer for the CLI and the MCP server, even when your app is in Node. The prompt installs the CLI with uv. See Installation.
  • The SDK's runtime for your app. A Python app uses solwyn, which needs Python 3.11 or newer. A Node app uses @solwyn/sdk 0.4.0, which needs Node 20 or newer. Use Node 22 or 24: current provider SDKs, such as OpenAI 7, need 22.
  • Nothing extra to store credentials. The CLI keeps your login and the project's API key in the OS keychain on macOS and Windows, and in a private 0600 file on Linux. On macOS and Windows the keychain must be usable where your agent runs commands; there is no fallback to the file. See Where credentials are stored.
  • A browser. No Solwyn account yet? You create one on the login page.

The prompt needs solwyn-cli 0.5.1 or newer. 0.5.0 stores an API key per project and writes .solwyn.env, and 0.5.1 writes agent guidance that hands the key to one command in a subshell; the guidance 0.5.0 writes tells agents to run a bare eval that exports the key into their shell. CLI 0.3.0 asks for an email and password instead, which the API no longer accepts, and 0.4.x stores the old sk_proj_ keys, which no longer work. The prompt replaces an older CLI. uv tool upgrade is not enough if you installed with a version pin such as solwyn-cli==0.3.0, because it keeps the pin. See Installation.

Two limits of solwyn init, which your agent runs:

  • It detects provider imports only in .py files. In a Node app it finds nothing, so your agent wraps the clients by following the TypeScript quickstart.
  • --agents writes its guidance files on Linux and macOS only. On Windows it fails with agent_artifact_write_failed.

Paste the prompt

Start Claude Code, Codex or Cursor in your repository. Replace BUDGET with a monthly cap in US dollars, such as 50, then paste the prompt.

Prompt to copy into your coding agent
Set up Solwyn spend controls in this repository. Docs: https://docs.solwyn.ai/coding-agent-setup

Solwyn caps what this app spends on LLM providers. You run every command. I only open links in my browser to sign up or sign in, verify my email, and approve. Never print, log or commit a Solwyn key or a provider key.

1. Check the CLI with: solwyn --version
   It prints solwyn and a version number. If solwyn is missing, or the version is older than 0.5.1, install or replace it with: uv tool install --python 3.11 'solwyn-cli>=0.5.1'
   If it was installed with pipx, use: pipx install --force 'solwyn-cli>=0.5.1'. With pip, use: python -m pip install --upgrade 'solwyn-cli>=0.5.1'
   Do not use uv tool upgrade: it keeps an old version pin. Then run solwyn --version again. If it still prints a version older than 0.5.1, stop and tell me: do not run solwyn init with an older CLI.
   The CLI needs Python 3.11 or newer, even when the app is in Node.

2. Log in. Run: solwyn --json login --wait 0
   It exits 6 with code login_pending and prints a URL and a code. Show me both, then stop and wait for me. I will open the URL, sign up or sign in, and approve. When I tell you it is approved, run: solwyn login --continue
   If it exits 3 with credential_storage_failed instead, the OS keychain could not be used. Show me the error and its hint, then stop. If I tell you to use the credentials file, run: solwyn --json login --store file --wait 0

3. Get the project and its key onto this computer. Work from the repository root.
   If there is no .solwyn.env at the repository root, create the project:
   solwyn --approval-wait 0 projects create --name <this repository's name> --budget BUDGET --mode hard_deny --store-key
   The command also writes .solwyn.env, which names the project.
   If .solwyn.env already exists, the repository already has a project. Do not create another. Check whether this computer holds its key with: solwyn --format table keys env > /dev/null
   If that succeeds, the key is already stored: go to step 4. If it exits 3 with api_key_not_stored, create a key for the repository's project and store it:
   solwyn --approval-wait 0 keys create --store-key
   It takes the project from .solwyn.env. If it fails with any other error, such as project_mismatch or project_not_found, show me the error and stop.
   Creating a project or a key needs my approval in the browser, so the command exits 6 with an approval URL and a retry command. Show me the URL, then stop and wait. When I tell you it is approved, run the retry command exactly as printed. The key goes straight to the CLI's credential store and is never shown.

4. From the repository root, run: solwyn init --agents
   It uses the project in .solwyn.env, checks the budget, prints SDK wiring for the providers it finds in .py files, and writes .claude/skills/solwyn/SKILL.md, .cursor/rules/solwyn.mdc and a marked section in AGENTS.md. Read that guidance and follow it. If init fails, show me its error code and hint. Do not work around it.
   Commit .solwyn.env with the other files. It names the project and holds no secret. Never change it, SOLWYN_PROJECT or --project to reach another project's budget.

5. Add the Solwyn MCP server to your own MCP configuration, with the guardrails profile. Get the exact command and arguments from: solwyn --json mcp-config --profile guardrails
   Claude Code: claude mcp add solwyn -- <command> <args...>
   Codex: a [mcp_servers.solwyn] table with that command, args and env_vars in ~/.codex/config.toml.
   Cursor: a "solwyn" entry under "mcpServers" in .cursor/mcp.json, with that command and args.
   Never put a key in the MCP configuration. Tell me if I need to restart you to load the server. If a Solwyn MCP tool returns an error, show me its code and message. Do not work around it.

6. Wrap every LLM provider client this app creates with the Solwyn SDK.
   Python: add the solwyn package (0.11.0 or newer) with this project's package manager and wrap each client with Solwyn(...), as init printed.
   Node: add @solwyn/sdk@0.4.0 and follow https://docs.solwyn.ai/typescript-sdk/quickstart. init does not scan .js or .ts files, so find the clients yourself.
   Provider keys stay in their environment variables, such as OPENAI_API_KEY, as init's wiring reads them.
   The SDK reads its key from SOLWYN_API_KEY and the project from SOLWYN_PROJECT. Do not write the key to .env or any other file, and never print it. To run the app, give both to that one command in a subshell, on one line, exactly as shown:
   (solwyn_env="$(solwyn --format table keys env)" && eval "$solwyn_env" && exec <command>)
   Never eval the output of solwyn keys env in your own shell. If solwyn keys env fails, show me its error and stop.
   Keep prompts, models and call signatures unchanged. Never add budget checks or confirms around calls the SDK wraps.

7. Set the SDK's budget mode to "hard_deny": budget_mode in Python, budgetMode in Node. Before you change fail_open (Python) or failOpen (Node), ask me. The default, true, lets calls through while Solwyn Cloud is unreachable. False is stricter, and the SDKs differ: Python blocks every call that no live run lease covers, and Node allows calls within the last budget limit it received and denies past it, or when it never received one.

8. Run: solwyn --json budget status
   Confirm that budget_mode is "hard_deny". If it is not, stop and tell me. Do not change it yourself.

9. Make one test call through each wrapped client, then run solwyn --json budget status again and show me the spend.

10. Some changes only I make: raising a cap, weakening enforcement, pausing rules, keys (including which projects a key reaches), billing and the team. Never run one on your own. If I ask you for one, run it with --approval-wait 0, show me the approval URL, and stop. Never try another route around an approval.

11. Summarize what you changed, file by file.

What you do while it runs

Your agent stops twice and waits for you.

  1. Approve the login. Your agent shows a URL and a code, such as KHJC-JKQS. Open the URL. Sign up, or sign in, and verify your email if the page asks. Check that the page shows the same code, then approve. Tell your agent it is approved.
  2. Approve the project, or the key. Your agent shows an approval URL, https://app.solwyn.ai/approve/…. In a repository that already has a project (its .solwyn.env is committed), it asks for a key for that project instead of a new project. The page describes the change. Approve it and tell your agent. It runs the retry command the CLI printed, which carries the approval.

After that your agent may ask you to restart it, so that it loads the MCP server. Then it finishes on its own.

On macOS or Windows, if your agent runs commands where the keychain is locked or out of reach, for example inside a sandbox or over SSH, the login stops with credential_storage_failed before it shows a code. Unlock the keychain and ask your agent to retry, or tell it to use the credentials file. It then runs solwyn login --store file, which saves that choice to config for later commands. See Where credentials are stored.

In a non-interactive run, such as claude -p or codex exec, "stop and wait" ends the turn. Approve in the browser, then resume the session and say "approved".

The login code expires after 10 minutes, and an approval request after 10 minutes. If one expires, ask your agent to run that step again. See Scoped login for what each outcome means.

On the Free plan an account gets one hard-cap project. If you already have one, creating a second hard_deny project fails at once with upgrade_required, before any approval is requested. Pick that project instead, or leave out --mode hard_deny.

What your agent can and can't change

The login your agent holds is scoped. It can read spend, budgets, alerts and runs, stop agent runs and lower a project's primary budget cap. Everything else needs your approval in the browser, each time: raising a cap, changing the enforcement mode, pausing or snoozing rules, keys, projects, billing, channels and the team. Your agent can ask for an approval. Only you, signed in to the dashboard, can give it. The login expires after 30 days. See Scoped login.

The MCP server's tools can't change your budget. The guardrails profile adds budget_check, budget_confirm, budget_check_batch and record_call to the read tools. They reserve budget for a call and record what it spent, with the API key for the repository's project. None of them raises a cap, changes the enforcement mode or pauses a rule. See the tool catalogue.

Your agent's standing rules live in the guidance init --agents writes: .claude/skills/solwyn/SKILL.md, .cursor/rules/solwyn.mdc and the Solwyn section of AGENTS.md. They tell agents to leave cap raises, enforcement changes, rule pauses, keys and billing to a human. See solwyn init.

To end the login once setup is done, and keep the project's API key for your app:

Terminal
solwyn credentials revoke --current

The CLI then holds only the API key. It can still read the project's budget and costs, check budget and record spend. solwyn logout also revokes the login, but it clears the stored API keys too.

Solwyn doesn't meter your coding assistant. The tokens Claude Code, Codex or Cursor spend on their own models never pass through Solwyn. Solwyn sees the calls your app makes through the SDK, and calls your agent reports itself with budget_check and budget_confirm or record_call.

Give the key to your app

The project's API key lives in the CLI's credential store: the OS keychain on macOS and Windows, a private 0600 file on Linux. The project's name lives in .solwyn.env at the repository root, which you commit:

.solwyn.env
# Solwyn project for this repo. Not a secret: commit this file.
SOLWYN_PROJECT="checkout-bot"

The SDK reads SOLWYN_API_KEY and SOLWYN_PROJECT. solwyn keys env prints export lines for both. Give them to one command in a subshell, so the hand-off creates no additional file holding the key and the key stays out of your shell's environment:

Terminal
(solwyn_env="$(solwyn --format table keys env)" && eval "$solwyn_env" && exec python app.py)

This is the form the agent guidance and solwyn keys env --help give.

  • The parentheses run the app in a subshell, so the key and the export end with it. Your shell never holds the key.
  • The && checks that the key was read. When no key for the project is stored on this computer, keys env exits 3 with api_key_not_stored and its error on stderr, and nothing runs. A teammate who clones the repository runs solwyn keys create --project <name> --store-key once.
  • --format table asks for the export lines that eval expects. keys env prints JSON only with --json or --format json on its own command line, never because of SOLWYN_FORMAT or your config. Never eval JSON output.

For a deployed app, put the key in your secret manager as SOLWYN_API_KEY, and set SOLWYN_PROJECT beside it. Never commit the key.

Choose hard_deny

The project's mode decides whether Solwyn blocks a call at the cap. solwyn projects create makes alert_only projects unless you pass --mode hard_deny, as the prompt does.

The SDK has its own defaults: budget_mode="alert_only" and fail_open=True in Python, budgetMode: "alert_only" and failOpen: true in Node. They don't override the project's mode. budget_mode only labels the results the SDK builds while Solwyn Cloud is unreachable. fail_open decides what happens then, and step 7 of the prompt leaves that choice to you:

SDKtrue (default)false
Python solwynCalls proceed and are tallied for the next check that reaches Solwyn.Every call that no live run lease covers raises BudgetExceededError. Lease-funded calls inside solwyn.run(...) keep flowing.
Node @solwyn/sdk 0.4.0Calls proceed, and their estimates are added to a local daily tally.Calls are allowed while this process's local daily estimate stays within the last budget limit it received, and denied past it. With no limit ever received, they are denied.

A run stop or hard denial the SDK already received still applies either way. See fail_open in Python, when the budget service is unreachable in Node and Budget enforcement.

To change an existing project's mode, run solwyn budget set --mode hard_deny as an owner or admin, then approve the change in the browser. The dashboard changes it too.

Check alerts and investigate

From your terminal:

Terminal
solwyn budget status
solwyn costs --group-by day --range 7d
solwyn alerts list --range 7d
solwyn alerts show <event_id>

Through MCP, ask your agent in plain words. For example: "Are we close to the Solwyn cap, and what alerts fired this week?" or "Which agent run cost the most yesterday, and on which model?" It answers with read tools such as get_project_status, budget_status, get_forecast, list_alert_events, get_costs, list_agent_runs and get_agent_run. Some reads depend on your plan.

The read tools use your login, so account-wide tools such as list_projects and list_alert_activity work too. With only an API key, the server answers that project's reads. See Agent integration for profiles, credentials and solwyn doctor --mcp.

On this page