toolgate

name	toolgate
description	Set up Toolgate in existing projects so coding agents can run selected CLIs through a sandboxed, gated command surface.

Toolgate Project Adoption

Use this skill when a user wants an agent project to adopt Toolgate, especially in Node, Bun, or Python repositories.

Toolgate config is JSON. Prefer project-local scripts that generate JSON and then run:

toolgate run --config <preset files> --config <project config> --profile agent -- <agent command>

Rules

• Install Toolgate from https://github.com/jmandel/toolgate by cloning the main branch and building it with Cargo.
• Keep direct tools simple. Use direct: ["bash", "node", "npm"] or a map to executable paths. Do not create presets for ordinary direct tools.
• Put host-authenticated tools in gated, not direct.
• Use profile.session.env, profile.session.files, and profile.session.mounts only for values that may be visible to the agent and all direct tools. These use the same value shapes as gated tool config, but they are not private per direct tool.
• Use bundled presets from the cloned Toolgate repo, such as ./.toolgate/repo/presets/github.json.
• If GitHub CLI access is needed, expose presets.gh-runtime. It injects GH_TOKEN from host gh auth token. Use gh-full only when the project intentionally wants to mount the host GitHub CLI config.
• Add generated Toolgate artifacts to project ignores: /.toolgate, /.toolgate.generated.json, and /toolgate.local.json.
• Keep generated config files readable and inspectable. Avoid hiding large YAML or JSON blobs inside package scripts.
• Be explicit about the security boundary. Gated tools hide credentials from the agent, but full presets still let the agent use the configured credential's full remote authority. Do not describe allow: "all" as readonly or safe.
• Treat argv policy as CLI-specific. Supervisor-controlled env closes one input path, but stdin, config files, default accounts, and remote side effects still matter.
• Keep tool sandboxes minimal by default. Do not add toolSandbox.root: "host", proc: true, or dev: "full" unless a tool actually needs that compatibility.

NPM Baseline

Add scripts like this:

{
  "scripts": {
    "toolgate:fetch": "rm -rf ./.toolgate/repo && git clone https://github.com/jmandel/toolgate ./.toolgate/repo",
    "toolgate:install": "npm run -s toolgate:fetch && cargo install --path ./.toolgate/repo --locked --force",
    "toolgate:config": "node ./scripts/toolgate.config.mjs > ./.toolgate.generated.json",
    "agent": "npm run -s toolgate:config && toolgate run --config ./.toolgate/repo/presets/github.json --config ./.toolgate.generated.json --profile agent -- ${AGENT:-codex}",
    "agent:codex": "AGENT=codex npm run -s agent",
    "agent:copilot": "AGENT=copilot npm run -s agent",
    "agent:claude": "AGENT=claude npm run -s agent"
  }
}

Add scripts/toolgate.config.mjs:

const config = {
  profiles: {
    agent: {
      session: {
        env: {
          AGENT_TOKEN_FILE: "/tmp/session-auth/token"
        },
        files: {
          "/tmp/session-auth/token": {
            from: "hostCommand",
            run: ["agent-cli", "auth", "token"]
          }
        }
      },
      gated: { gh: "presets.gh-runtime" },
      direct: ["bash", "node", "npm"]
    }
  }
};

process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);

Bun Baseline

Use the same Toolgate install/fetch scripts, but generate config with Bun when that fits the project:

{
  "scripts": {
    "toolgate:config": "bun ./scripts/toolgate.config.ts > ./.toolgate.generated.json",
    "agent": "bun run toolgate:config && toolgate run --config ./.toolgate/repo/presets/github.json --config ./.toolgate.generated.json --profile agent -- ${AGENT:-codex}"
  }
}

The generated profile should usually expose direct tools such as ["bash", "bun"].

Python Baseline

Python projects can either keep a checked-in toolgate.local.json or generate JSON from a tiny script:

python3 scripts/toolgate_config.py > .toolgate.generated.json
toolgate run --config ./.toolgate/repo/presets/github.json --config ./.toolgate.generated.json --profile agent -- codex

Use direct tools like ["bash", "python3"]. Keep pip, uv, or other networked package tools gated if they need host auth or config.

Verification

After editing a project, verify:

npm run toolgate:install
npm run toolgate:config
toolgate resolve --config ./.toolgate/repo/presets/github.json --config ./.toolgate.generated.json --profile agent
npm run agent:codex -- --help

Swap agent:codex for agent:copilot or agent:claude when those are the target CLIs.

More examples live in references/adoption-patterns.md.