# how to scope an agent to one repo or service

## TL;DR
Give the agent its own credentials that can reach exactly one repo or service and nothing else. Least privilege is not a philosophy here, it is a blast-radius setting. When the agent goes sideways, "sideways" should mean one repo, not the whole org.

```text
how to scope an agent to one repo or service
```

## Use this when
- An agent works on one codebase, one service, or one dataset
- You are connecting an agent to GitHub, your cloud, or a production API
- A past incident involved an agent touching systems outside its task
- You want a template for scoping every new agent the same way

## Not for this skill when
- The agent legitimately orchestrates across many services (scope per task instead)
- You are scoping what the agent can read on the web (that is URL allowlisting)
- The agent only needs read access to docs (still scope it, but the risk is low)

## Steps

**1. Create a dedicated service account for the agent.**

Not your account, not a shared bot account. One account per agent, named after it. Everything the agent does is then attributable and revocable in one move.

Expected: the agent authenticates as its own identity everywhere it goes.

**2. Grant it access to exactly one repo or service.**

Add the account as a collaborator on that one repo, or attach the one IAM role for that one service. Default to read; add write only if the task needs it, and never admin.

```yaml
scope:
  repos:
    - myorg/payments
  permissions: read
  deny:
    - "*"
```

Expected: a permission record showing one repo, minimal permissions, explicit deny elsewhere.

**3. Enforce path allowlists inside the agent's file tools.**

Even within the repo, restrict which paths the agent's tools can touch if the task is narrow. A docs-fixing agent does not need write access to the deploy scripts.

Expected: a write outside the allowed paths fails at the tool layer with a clear denial.

**4. Block the cross-repo escape hatches.**

Agents are creative: they will try package registries, CI configs, submodules, and API tokens they find in the repo to reach further. Scope the token so those paths dead-end, and strip CI secrets the agent does not need.

Expected: the agent's token returns permission denied on any repo or API outside its scope.

**5. Test the boundary with a denied action.**

Before going live, have the agent (in a sandbox) try to read another repo, list org members, or call an out-of-scope API. Every attempt should fail. If one succeeds, your scoping has a hole.

```
gh api /repos/myorg/other-service --header "Accept: application/json"
```

Expected: a permission-denied response, proving the token cannot see the other repo.

**6. Review the scope when the task changes.**

Tasks creep. When the agent takes on a second repo, go through this list again deliberately instead of widening permissions in a hurry. Each scope expansion is a small security decision; make it consciously.

Expected: a changelog of scope grants with dates and reasons, reviewed quarterly.

### Variant: least privilege for AI agents
This skill is least privilege applied to agents: dedicated identity, minimal permissions, explicit denies, tested boundaries. The principle is old; agents just make violations faster and weirder.

### Variant: agent only access one github repo
Use a fine-grained personal access token or a GitHub App installation limited to that repo, with contents read or write as needed. Never use a classic token with broad scopes for an agent.

### Variant: restrict agent to a single service
Same pattern outside GitHub: one IAM role, one service, resource-level permissions where the platform supports them. Name the role after the agent so the next person understands it.

### Variant: scoped API keys for agents
Issue per-agent keys with the narrowest scopes the provider offers, short expiries, and IP or referrer restrictions where available. One key per agent per integration, so rotation is surgical.

## Why this happens
The default is always too broad: people hand agents their own credentials or a shared admin token because it works immediately. That works right up until the agent misreads a task and the blast radius is the entire organization. Scoping feels slow on day one and looks brilliant on the day something goes wrong.

## Edge cases and pitfalls
- **The agent needs a second repo "just this once":** do the full scoping pass for the second repo. "Just this once" permissions are how agents end up with org-wide read.
- **Tokens with more scopes than the UI shows:** audit the actual token scopes via the provider's API, not the settings page you clicked through. Providers add scopes to defaults quietly.
- **The agent finds credentials inside the repo:** that is a separate finding: rotate those credentials and remove them from the repo. The agent was not supposed to see them either.
- **CI pipelines run as the agent:** CI jobs inherit whatever the agent can do. Scope the CI role separately and do not let the agent edit workflow files unless that is the task.
- **Scope is right but the agent is shared across tasks:** one agent doing five jobs with one repo's scope will eventually need a sixth repo. Split agents by task instead of widening one agent forever.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gJfaiGHDhxxaHyKUQP9_EA