> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Sauce CLI or TypeScript library, connect a coding agent, and configure chain access.

Choose the setup that matches your workflow. For the terminal quickstart, you only need the command-line tool. Connect an agent if you want it to write and test programs, or install the library in your application.

## Prerequisites

* Node.js 24 or newer. `node --version` prints the version you have.
* npm, which comes with Node.js.

The SDK ships under the Eco, Inc. Proprietary License 1.1, the `LICENSE.md` file in the `@eco-incorp/sauce` package, which holds its terms. Its Additional Use Grant begins:

> Notwithstanding the restrictions in this License, you may do the following, in each case solely to create, compile, test, simulate, and execute programs for use with the Authorized Contracts (the "Licensed Purpose"):

Sauce transactions need no API key. For a use the license does not cover, contact Eco at [partners@eco.com](mailto:partners@eco.com).

## Install the command

```bash theme={null}
npm install -g @eco-incorp/sauce
```

Check the install:

```bash theme={null}
sauce --version
```

```text theme={null}
@eco-incorp/sauce <version>
```

Every command takes `--help`, which lists what the command does and every flag it accepts.

### Run it without installing

```bash theme={null}
npx -y @eco-incorp/sauce <command>
```

npx fetches the package and runs the command. Outside a project that depends on `@eco-incorp/sauce`, never run a bare `npx sauce`: npx then fetches an unrelated npm package named `sauce`.

## Install it in a project

```bash theme={null}
npm install @eco-incorp/sauce viem
```

This installs the TypeScript library. In that project, `npx sauce <command>` runs the version the project's `package.json` pins; a global `sauce` run there runs the global version. The library's EVM API takes and returns viem types. [TypeScript overview](https://docs.eco.com/sauce-sdk/typescript/overview.md) lists the import paths.

To create a project with the CLI, run:

```bash theme={null}
sauce init my-app
cd my-app
npm install
```

`sauce init` writes these files, then installs the agent skills:

* a `package.json` that pins `@eco-incorp/sauce` to the version that ran it;
* `AGENTS.md`, plus `CLAUDE.md` and `GEMINI.md` that import it;
* `.gitignore`;
* `sauce.config.example.json`;
* `programs/tsconfig.json`, so an editor type-checks the programs in `programs/`.

See [sauce init](https://docs.eco.com/sauce-sdk/cli/init.md).

## Add the MCP server to your agent

The MCP server lets an agent compile and simulate programs through tools. The agent starts it as a local process and communicates over standard input and output (stdio). You do not need to run that process separately.

For a shared project, use [project configuration](#write-the-project-files-for-every-agent) to pin the server version. To configure an individual agent, choose it below:

**Claude Code**

```bash theme={null}
claude mcp add sauce -- sauce mcp
```

**Codex**

```bash theme={null}
codex mcp add sauce -- sauce mcp
```

A project Codex trusts can carry the same server in `.codex/config.toml`:

```toml theme={null}
[mcp_servers.sauce]
command = "sauce"
args = ["mcp"]
```

**Cursor**

In `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:

```json theme={null}
{
  "mcpServers": {
    "sauce": { "command": "sauce", "args": ["mcp"] }
  }
}
```

**VS Code (Copilot)**

In `.vscode/mcp.json`, under `servers`:

```json theme={null}
{
  "servers": {
    "sauce": { "type": "stdio", "command": "sauce", "args": ["mcp"] }
  }
}
```

**Gemini CLI**

```bash theme={null}
gemini mcp add sauce sauce mcp
```

**Claude Desktop**

Open **Settings**, then **Developer**, then **Edit Config**. Add the server under `mcpServers` in `claude_desktop_config.json`, then restart Claude Desktop:

```json theme={null}
{
  "mcpServers": {
    "sauce": { "command": "sauce", "args": ["mcp"] }
  }
}
```

A desktop client may not see your shell's `PATH`, and then cannot start a `sauce` installed under nvm or another version manager. `sauce` is a Node.js script that starts with `#!/usr/bin/env node`, so the absolute path of `sauce` alone is not enough: Node must be found too. Give the absolute path that `which node` prints as the command, and the path that `which sauce` prints, then `mcp`, as the args. `npx` is a Node.js script as well, so the alternative, command `npx` with args `["-y", "@eco-incorp/sauce", "mcp"]`, also needs Node on the client's `PATH`.

### Write the project files for every agent

```bash theme={null}
sauce mcp setup
```

`sauce mcp setup` writes the server into each agent's project file and keeps everything else in that file:

| Agent | File |
| - | - |
| Claude Code | `.mcp.json` |
| Codex | `.codex/config.toml` |
| Cursor | `.cursor/mcp.json` |
| VS Code (Copilot) | `.vscode/mcp.json` |
| Gemini CLI | `.gemini/settings.json` |

These files are shared through version control, so the entry does not depend on a global install. It runs `npx -y @eco-incorp/sauce@<version> mcp`, where `<version>` is the exact version of the `sauce` that ran setup, with no wallet flags: the server serves `~/.sauce/wallets` ([Agents, wallets and keys](https://docs.eco.com/sauce/security-considerations.md#agents-wallets-and-keys)). `--agent claude,cursor` limits it to those agents. `--force` replaces an existing `sauce` entry that differs. A file that is not plain JSON stops `setup` with exit code `2`, after the files before it are written. [sauce mcp](https://docs.eco.com/sauce-sdk/cli/mcp.md#sauce-mcp-setup) lists every flag.

### Runtime packages

The MCP server loads two packages that are optional peer dependencies of `@eco-incorp/sauce`: the MCP SDK and `zod`. A Solana simulation in a local copy loads LiteSVM. These packages are resolved in this order:

1. Your own copies, if they are exactly the versions the package pins.
2. Otherwise, a runtime folder under `~/.sauce/runtime/`. The first use installs it, and so does `sauce mcp setup`.

To install the folder ahead of time, or to see where each package comes from:

```bash theme={null}
sauce runtime install
sauce runtime
```

See [sauce runtime](https://docs.eco.com/sauce-sdk/cli/runtime.md).

## Install the agent skills

```bash theme={null}
sauce skills install
```

This copies the package's agent skills into the project:

* `.claude/skills/` is read by Claude Code;
* `.agents/skills/` is read by Codex, Cursor, Copilot and Gemini CLI.

`sauce skills status` reports each directory as up to date, outdated or modified. `sauce skills update` brings the directories to the installed version. A file you edited is kept unless you pass `--force`. The MCP server also serves the same skills as tools and resources, so an agent connected to it needs nothing installed in the project. See [sauce skills](https://docs.eco.com/sauce-sdk/cli/skills.md).

## Configure endpoints

An RPC endpoint is the connection a command uses to read blockchain state. The CLI uses a built-in public endpoint unless you provide one. Public endpoints can be slow or rate-limited, and each read through one prints a note on stderr.

The following commands use the `pay.sauce.ts` program from the [quickstart](https://docs.eco.com/quickstarts/sauce/first-program.md). To choose an endpoint for one command:

```bash theme={null}
sauce simulate pay.sauce.ts --chain base --owner <address> --rpc-url <url> --args <recipient> 1000000
```

Or give a file of endpoints, keyed by chain id:

```json rpc.json theme={null}
{ "rpcUrls": { "1": "<url>", "8453": "<url>", "1399811149": "<url>" } }
```

```bash theme={null}
sauce simulate pay.sauce.ts --chain base --owner <address> --config rpc.json --args <recipient> 1000000
sauce mcp --config rpc.json
```

`--offline` reads no chain at all, not even through a built-in endpoint. `sauce compile` works offline. A command that needs the chain refuses:

```text theme={null}
sauce simulate: --offline reads no chain, and this reads base
```

[Chains, endpoints and fees](https://docs.eco.com/sauce-sdk/cli/chains-and-endpoints.md) covers fallback between public endpoints, `eth_simulateV1`, and Arc's fees.

## Updates

Run `sauce update --check` to compare your installed version with the latest release. Follow [Package updates](https://docs.eco.com/sauce-sdk/operating/upgrading.md) to update the command, project dependency, agent configuration and skills together.

## Troubleshooting

* **Unsupported Node.js version:** check `node --version` and use Node.js 24 or newer.
* **Your agent cannot find the command:** a desktop app may use a different `PATH` from your shell. Configure the absolute paths to Node.js and `sauce`, as described above.
* **RPC requests fail or are rate-limited:** use your own endpoint and check [endpoint troubleshooting](https://docs.eco.com/sauce-sdk/operating/troubleshooting.md#endpoints-and-rate-limits).
* **An MCP server fails to start:** check [MCP setup troubleshooting](https://docs.eco.com/sauce-sdk/operating/troubleshooting.md#mcp-setup), including runtime packages and pinned versions.

## Next steps

* [Quickstart](https://docs.eco.com/quickstarts/sauce/first-program.md): write, compile, simulate and build a program on Base.
* [AI agents](https://docs.eco.com/sauce-sdk/ai-agents.md): what an agent does with the server and the skills.
* [CLI overview](https://docs.eco.com/sauce-sdk/cli/overview.md): every command.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.