User Guides

1. Policy Writing Guide

Governance policies control which tools your agents are allowed to call. Policies are evaluated on every tool call before it reaches the external service.

What is a governance policy?

A policy is an ordered list of rules. Each rule has an effect (allow or deny) and a tool pattern that matches one or more tool names. Rules are evaluated in order — the first match wins. If no rule matches, the default is deny.

Wildcard patterns

Priority ordering

Rules are evaluated top-to-bottom. The first matching rule wins — later rules do not override it. Put specific rules before wildcards. A deny rule does not “override” an allow by virtue of being a deny — it only wins if it appears first in the list.

Recipe: Allow agent to use only memory tools

Useful for a focused research agent that should only read and write persistent memory.

{
  "name": "Memory tools only",
  "rules": [
    { "effect": "allow", "tool": "memory_*" },
    { "effect": "deny",  "tool": "*" }
  ]
}

Recipe: Deny all GitHub write operations

Grant read-only access to GitHub. The agent can list issues and search code but cannot create PRs, push commits, or merge branches.

{
  "name": "GitHub read-only",
  "rules": [
    { "effect": "deny", "tool": "github_create_*" },
    { "effect": "deny", "tool": "github_update_*" },
    { "effect": "deny", "tool": "github_delete_*" },
    { "effect": "deny", "tool": "github_merge_*" },
    { "effect": "allow", "tool": "github_*" }
  ]
}

Recipe: Allow everything except delete operations

A safe default for agents that need broad access but should not be able to destroy data.

{
  "name": "No delete operations",
  "rules": [
    { "effect": "deny",  "tool": "*_delete" },
    { "effect": "deny",  "tool": "*_remove" },
    { "effect": "allow", "tool": "*" }
  ]
}

2. Tool Integration

External tools (GitHub, Slack, and others) connect via OAuth. Once authorized, your agent can call any tool from that provider.

OAuth setup flow

1. Go to Dashboard → Connections.
2. Find the provider (GitHub, Slack, Jira, Linear, or Notion).
3. Click Connect — you will be redirected to the provider's OAuth consent screen.
4. Approve the requested scopes.
5. You will be redirected back to the Dashboard. The connection status will show Connected with the authorized account name.

GitHub tools

After connecting GitHub, your agent gets access to tools for issues, pull requests, code search, and repository management.

// List open issues in a repository
await mcp.callTool("github_list_issues", {
  owner: "your-org",
  repo: "your-repo",
  state: "open",
  limit: 20
});

Slack tools

After connecting Slack, your agent can post messages, search conversation history, and list channels.

// Post a message to a Slack channel
await mcp.callTool("slack_post_message", {
  channel: "#engineering",
  text: "Deploy to production completed successfully."
});

Memory Cloud tools

ShackleAI Memory is available to all plans with no OAuth setup required. It provides 11 tools for persistent agent memory:

See the Tool Guides for detailed usage examples for each tool.

3. Agent Setup

Agents are named configurations that group a set of tools and policies. You can run multiple agents under a single account, each with different permissions.

Creating an agent

1. Go to Dashboard → Agents and click New Agent.
2. Give the agent a descriptive name (e.g., “Code Review Bot”).
3. Select the tools this agent should have access to.
4. Optionally attach a policy to restrict what the agent can do (see Policy Writing Guide above).
5. Click Create. The agent is assigned a unique agent ID.

Account API key vs. agent API key

Use agent-scoped keys in production. If the key is compromised, only that agent's tools are exposed, not your entire account.

Monitoring agent activity

Go to Dashboard → Observatory to see a real-time log of every tool call made by your agents. Filter by agent, tool, status, or date range. Export logs as CSV for auditing.

4. Billing Guide

Plan comparison

What counts as usage?

• Each successful tool call counts as one API call.
• Failed calls (4xx errors) do not count toward your usage quota.
• Rate-limited calls (429) do not count.
• Memory tool calls and external tool calls are counted separately.

Upgrade or downgrade

1. Go to Dashboard → Settings → Billing.
2. Click Manage Subscription — this opens the Stripe billing portal.
3. Select your new plan and confirm.
4. Changes take effect immediately. Upgrades are prorated. Downgrades take effect at the start of the next billing cycle.

Enterprise pricing

Enterprise plans include custom rate limits, dedicated infrastructure, SSO, audit logs, and a custom SLA. Contact us to discuss pricing.

5. Troubleshooting

Common errors and how to resolve them. Every ShackleAI error response includes a code field with a machine-readable error identifier.

401 Unauthorized — API key issues

This error means the API key was not recognized. Common causes:

• The key was copied incorrectly — ensure it starts with sk_shackle_.
• The key was deleted or regenerated — generate a new one in Settings.
• The Authorization header format must be Bearer sk_shackle_....

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "status": 401
  }
}

403 Policy Denied — governance blocking

A governance policy is blocking the tool call. The details field tells you which policy and rule matched. To resolve:

• Review the named policy in Dashboard → Policies.
• Add an allow rule for the specific tool, or use a more permissive wildcard.
• Remember: the first matching rule wins — put allows before denies if needed.

{
  "error": {
    "code": "POLICY_DENIED",
    "message": "Tool call blocked by governance policy",
    "status": 403,
    "details": {
      "tool": "github_delete_branch",
      "policy": "GitHub read-only",
      "rule": "deny github_delete_*"
    }
  }
}

429 Too Many Requests — rate limits

The retry_after field (in seconds) tells you how long to wait before retrying. Free plans have lower limits. Upgrade to Developer or Team for higher limits, or add exponential backoff to your agent's retry logic.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "status": 429,
    "details": {
      "limit": 100,
      "window": "60s",
      "retry_after": 23
    }
  }
}

Connection failed — OAuth token expired

OAuth tokens expire or are revoked when you change permissions or revoke app access in the provider. To fix: go to Dashboard → Connections, find the affected provider, and click Re-authorize.

{
  "error": {
    "code": "CONNECTION_FAILED",
    "message": "OAuth token expired or revoked for GitHub",
    "status": 503,
    "details": {
      "provider": "github",
      "action": "Re-authorize at /dashboard/connections"
    }
  }
}

MCP config issues

If your MCP client shows ShackleAI as disconnected or the agent cannot find ShackleAI tools, verify the config in your client:

# Remove and re-add the MCP server
claude mcp remove shackleai
claude mcp add shackleai \
  --transport sse \
  https://gateway.shackleai.com/mcp \
  --header "Authorization: Bearer sk_shackle_YOUR_KEY"

# Verify it appears in the list
claude mcp list