# tooling.json `tooling.json` is the trust boundary for your Swytchcode project. It defines **what your project is allowed to execute**. Every method and workflow that Swytchcode can run must be explicitly listed in this file. If a tool is not present here, execution is blocked. This file also marks the root of a Swytchcode project. Whenever a command is executed, the CLI searches upward from the current directory until it finds a `.swytchcode/tooling.json` file. ``` project/ ├── .swytchcode/ │ ├── tooling.json │ ├── integrations/ │ └── ... └── ... ``` > **Important** > > Swytchcode follows a fail-closed model. Nothing can execute unless it has been explicitly added to `tooling.json`. --- ## File Structure A minimal `tooling.json` looks like this: ```json { "version": "1.0", "mode": "production", "editor": "cursor", "integrations": {}, "tools": {} } ``` As your project grows, Swytchcode automatically updates this file whenever you add integrations, methods, or workflows. --- ## Top-level Fields ### version Defines the schema version of the configuration file. ```json { "version": "1.0" } ``` This value is created automatically during project initialization. --- ### mode Controls which environment Swytchcode executes against. ```json { "mode": "production" } ``` Supported values: | Value | Description | |--------|-------------| | `production` | Uses the production endpoint defined in `manifest.json`. | | `sandbox` | Uses the sandbox endpoint defined in `manifest.json`. | The execution mode determines which base URL Swytchcode resolves before sending an API request. --- ### editor Specifies the coding agent or editor configured for the project. ```json { "editor": "cursor" } ``` Supported editors: - cursor - claude - codex - copilot - gemini - hermes - openclaw - windsurf - none Swytchcode uses this value during project initialization to generate editor-specific rules and MCP configuration. --- ### integrations Tracks every integration installed in your project. ```json { "integrations": { "stripe.stripe": { "version": "v2" }, "github.github": { "version": "v1" } } } ``` Each entry pins a specific version so every developer and AI agent uses the same integration contract. --- ### tools The `tools` object contains every trusted method and workflow available for execution. ```json { "tools": { "stripe.create_payment": {}, "github.repo.star": {} } } ``` Nothing outside this list can be executed. The following sections explain how methods and workflows are represented. --- ### permissions Optionally restricts network and filesystem access. ```json { "permissions": { "network": [ "api.stripe.com" ] } } ``` If omitted, Swytchcode applies no additional restrictions. --- ## Method Entries A method represents a single executable API operation. Each method contains: - type - summary - description - integration - inputs Example: ```json { "api.cluster.create": { "type": "method", "summary": "Create a new cluster instance", "desc": "Create a new cluster instance", "integration": "weaviate.lyrid@v1", "inputs": [ { "Authorization": { "LOCATION": "header", "TYPE": "STRING" } } ] } } ``` ### Fields | Field | Description | |--------|-------------| | `type` | Always `"method"` | | `summary` | Short description of the method | | `desc` | Detailed description | | `integration` | Integration providing the method | | `inputs` | Required request inputs | Methods are added automatically when you run: ```bash swy add method ``` --- ## Workflow Entries A workflow represents multiple methods executed in sequence. Unlike methods, workflows do **not** duplicate their internal steps as top-level tools. Example: ```json { "workflow.example": { "type": "workflow", "name": "Example Workflow", "integration": "weaviate.lyrid@v1", "steps": [ { "canonical_id": "api.cluster.create", "index": 0, "integration": "weaviate.lyrid@v1", "inputs": [] }, { "canonical_id": "api.cluster.update", "index": 1, "integration": "weaviate.lyrid@v1", "inputs": [] } ] } } ``` ### Workflow Fields | Field | Description | |--------|-------------| | `type` | Always `"workflow"` | | `name` | Workflow name | | `integration` | Integration containing the workflow | | `steps` | Ordered execution steps | Each step contains: - canonical_id - integration - inputs - index The `index` determines execution order. ``` Step 0 ↓ Step 1 ↓ Step 2 ``` When a workflow executes, Swytchcode runs each step sequentially. --- ## Permissions The optional `permissions` block limits where tools are allowed to interact. Example: ```json { "permissions": { "network": [ "api.stripe.com", "api.sendgrid.com" ], "filesystem": [ "/var/app/uploads" ] } } ``` ### Network Defines an allowlist of hosts. If a request targets any other hostname, execution fails. ```json { "network": [ "api.stripe.com" ] } ``` --- ### Filesystem Defines directories Swytchcode may access. ```json { "filesystem": [ "/var/app/uploads" ] } ``` Filesystem permissions are reserved for future enforcement. --- ## Managing Tools Most developers should never edit `tooling.json` manually. The CLI keeps this file synchronized. ### Add a method ```bash swy add method stripe.create_payment # shorthand - identical to the above swy add stripe.create_payment ``` `add method` reads the Wrekenfiles and bundles already fetched under `.swytchcode/integrations/`, resolves the method's input/output STRUCTs into a concrete schema, and writes the result into `tooling.json.tools`. It also stores a `method_hash` (a SHA-256 of the Wrekenfile entry) alongside the tool - `swy sync` uses this hash later to warn you if the upstream definition has changed since you added it. If multiple integrations expose the same canonical ID, Swytchcode asks you to select the correct one interactively. In non-interactive contexts (CI, scripts), pass an explicit `project@library.version` spec ahead of the canonical ID to disambiguate instead of relying on the picker - see `swy add method [spec] ` in the [Command Reference](/reference/commands/#swy-add). Two flags matter here: - `--all ` adds every method for a project at once, skipping any canonical ID that's already present - useful right after `swy get` when you want the whole integration enabled rather than cherry-picking methods one at a time. - `--no-auto-install` skips auto-downloading missing library dependencies for multi-library workflows. Use it if you want to add a workflow's entry without silently pulling in every dependency it touches. --- ### Add a workflow ```bash swy add workflow workflow.payment.checkout ``` Unlike methods, a workflow entry does not duplicate its steps as separate top-level tools in `tooling.json.tools` - see [Workflow Entries](#workflow-entries) below. Missing integrations referenced by the workflow's steps are downloaded automatically before the entry is written. --- ### Register an integration ```bash swy add integration stripe.stripe@v2 ``` Registers an integration without downloading its bundle. --- ### List enabled tools ```bash swy list tooling swy list tooling stripe # filter by a pattern swy list tooling --json ``` `swy list` reads only local state (`.swytchcode/integrations` and `tooling.json`) - it never calls the registry, so it works offline. The `tooling` filter specifically reads `tooling.json.tools` and shows only what's been explicitly enabled via `swy add`, as opposed to `swy list methods` / `swy list workflows`, which show everything available in the fetched bundles whether or not it's enabled. `--json` returns a machine-readable array: `[{ "canonical_id": "stripe.create_payment", "integration": "stripe.stripe@v2" }, ...]`. Always verify a tool appears in this output - not just in `swy list methods` - before generating execution code or wiring it into an AI agent's tool list; a method existing in the bundle doesn't mean it's trusted for execution. --- ## Best Practices - Do not edit generated entries unless necessary. - Commit `tooling.json` to version control. - Use `swy add` instead of manually creating tools. - Keep integration versions pinned for reproducible execution. - Review enabled tools periodically to remove unused capabilities. --- Now that you understand how Swytchcode defines trusted tools, continue with: ## Next Steps - [manifest.json](https://docs.swytchcode.com/configuration/manifest-json/) - Learn how integrations define endpoints, authentication, retries, and execution policies. - [policies.json](https://docs.swytchcode.com/configuration/policy-json/) - Learn how to apply runtime guardrails and validation rules before execution.