tooling.json, manifest.json, and policies.json Explained: Swytchcode's Config Files

Every Swytchcode project is built from a small stack of local files under .swytchcode/. You rarely edit most of them by hand, but each one answers a specific question about your project: what an integration can do, what you've downloaded, what you've actually trusted, and what you've restricted even after trusting it. Knowing which file answers which question makes it far easier to understand what a given CLI command is doing, and to debug it when something isn't behaving the way you expect.

wrekenfile.yaml: The Integration Spec

wrekenfile.yaml is the full specification for an integration: method shapes, HTTP definitions, endpoint paths, validation rules, and input and output types. It's fetched automatically by swy get and stored under .swytchcode/integrations/, alongside the integration's methods and workflows.

Think of it the way you'd think of a lockfile for a package manager. You don't usually write or edit it yourself. It exists so that everything downstream, manifest.json, tooling.json, and ultimately swy exec, has one exact, versioned source of truth for what an integration's methods actually look like. When swy add enables a method, it's reading the method's shape out of the Wrekenfile to build the resolved schema it stores in tooling.json.

manifest.json: What's Actually on Disk

manifest.json tracks the integration bundles you've downloaded and the resolved, per-environment base URLs for each one, production versus sandbox, for example. It's written by swy get when you fetch a single integration, and by swy bootstrap when you fetch everything declared in tooling.json.integrations at once, typically in CI. Both commands, along with everything else in this guide, are covered in full in the Swytchcode CLI Commands reference.

The distinction worth holding onto: manifest.json reflects what's downloaded to disk and where it points. tooling.json reflects what's actually enabled for execution. You can have an integration sitting in manifest.json that isn't enabled anywhere in tooling.json yet, and that's completely normal, it just means you've fetched it but haven't added any of its methods.

tooling.json: The Trust Boundary

tooling.json is the file that determines what your project is actually allowed to execute. It's created empty by swy init, and it stays empty until you explicitly enable something with swy add.

This separation matters: downloading an integration with swy get does not enable anything by itself. A tool only becomes callable once it has an entry in tooling.json, added either directly (swy add <canonical_id>) or through the more explicit swy add method / swy add workflow / swy add integration subcommands.

Enabling a method does more than register its name. swy add embeds that method's full resolved input schema directly into tooling.json: required fields, optional fields, header parameters, and any idempotency key the method uses. From that point on, the CLI knows exactly what a valid call looks like and enforces it at runtime, rather than finding out from the API's own error response. Each enabled method is also stored with a hash of its definition, which is how swy sync can later detect and warn you if the underlying integration has changed since you added it.

tooling.json can also carry permission rules scoped to the project itself. One real example: a project's tooling.json included a permissions.network array listing the exact hosts it was allowed to reach.

{
  "permissions": {
    "network": [
      "api.stripe.com",
      "api.hubapi.com"
    ]
  }
}

Remove a host from that array, and any request to it gets blocked locally, before a single byte leaves your machine, with a permission_denied error. Nothing needs to be redeployed or restarted for that to take effect; it's read on the next execution.

Because it's the actual trust boundary, swy list tooling is the fastest way to confirm exactly what a project can do right now, without needing to check the registry or any integration bundle.

policies.json: The Guardrails

policies.json holds method-level guard-policy rules, stored under .swytchcode/integrations/policies.json. These rules get evaluated before every single swy exec call, not just at setup time, which is what makes them an active guardrail rather than a one-time check.

You manage this file through swy policy, not by hand:

swy policy add
swy policy list [--json]
swy policy remove
swy policy validate

add walks you through creating a rule interactively. remove takes a policy ID. validate checks the file against its schema, useful after any manual edits or before deploying a change. Past violations of these rules are viewable, read-only, through swy audit policy, separate from managing the rules themselves.

While tooling.json permissions like the network allowlist above are project-wide restrictions on where requests can go, policies.json is where finer-grained, per-method rules live, the kind of thing you'd use to say a specific method can run, but only under certain conditions.

How the Four Fit Together

A simple way to hold all four in your head: wrekenfile.yaml is the spec, what an integration's methods are capable of, in full. manifest.json is what you have, the bundle downloaded to disk and where it points. tooling.json is what you trust, the specific methods you've actually enabled, each with its schema resolved and locked in. policies.json is what you allow even after something is trusted, the rules checked on every single call.

A method has to clear every layer, specified, downloaded, enabled, and policy-compliant, before swy exec will actually run it.

Frequently Asked Questions

Do I need to edit these files by hand? Generally no. wrekenfile.yaml and manifest.json are written when you run swy get, tooling.json is written by init and add, and policies.json is managed through swy policy. Manual edits are supported, but should be checked with swy policy validate afterward for the policy file.

What's the difference between fetching an integration and enabling it? swy get downloads the integration's spec and bundle, and updates manifest.json. It does not make anything callable. swy add is the separate step that reads that spec and actually enables a specific method or workflow in tooling.json, with its schema resolved and embedded.

What exactly gets stored when I enable a method with swy add? Its full resolved input schema, required fields, optional fields, header parameters, and any idempotency key it uses, plus a hash of its definition so swy sync can detect if it later changes upstream.

How do I see what's currently enabled in my project? Run swy list tooling. It reads local state only and shows exactly what's been added via swy add.

What happens if an integration changes after I've already added it? swy sync re-checks the hash of every enabled method against what's currently in tooling.json. If one has changed, it warns you and tells you to re-run swy add on that method to refresh it.

Can I restrict which network hosts a project is allowed to reach? Yes. A project's tooling.json can include a permissions.network allowlist. Any request to a host not on that list is blocked locally before it reaches the network at all.

Where to Go Next

• tooling.json Reference: the full schema and field reference
• policies.json Reference: the full policy rule schema
• manifest.json Reference: the full manifest schema
• How to Set Up Policy Guardrails: using swy policy in practice
• Swytchcode CLI Commands: every command that reads or writes these files