SF Claws

Self-hosting

Run SF Claws on your own infrastructure

SF Claws is a Node.js control plane you deploy yourself, plus a Chrome extension you can install from the Chrome Web Store. Your Salesforce refresh tokens, GitHub tokens and model keys stay in your deployment, encrypted per client under a master key you hold.

Full deployment guide on GitHubJump to the steps

Key architecture

Three parts, one place where anything agentic runs

The extension and the admin console talk to the control plane over HTTPS and server-sent events. The control plane talks to Salesforce over OAuth and the Metadata API, to GitHub over the Git Data API, and to your model provider over its messages API. Nothing else has credentials.

Chrome MV3, LWC OSS, Tailwind

Chrome side panel

Renders the chat, plan, changes, explorer, notes and GitHub tabs, and reports which Salesforce page the user is on with every message. It never calls Salesforce, GitHub or a model provider itself.

Node.js, Fastify, SQLite

Control plane

Users, roles and approvals, clients and orgs, GitHub per client, model bindings, skills, policies, spend ceilings, the agent runtime and swarm, knowledge sources and the audit log. Everything agentic runs here.

LWC OSS, Tailwind, Vite

Admin console

Where super admins configure providers, models, clients, policies and standing instructions, approve users and extension pairings, and review every session end to end.

Repository layout

An npm workspaces monorepo on Node 22. Build order is shared, server, admin console, extension. The contract package changes first; everything else reads its output.

packages/shared
The contract: zod schemas for entities, REST routes, session events and SFDX source-format helpers.
packages/server
Control plane and agent runtime. Fastify, better-sqlite3, jsforce, Octokit, and the Anthropic, OpenAI, DeepSeek and DeepInfra providers.
packages/admin-ui
The admin console.
packages/extension
The Chrome MV3 side panel.
skills/
Default markdown skills seeded on first boot: policy, quality and playbooks.
docs/
Architecture, tenancy, deployment, admin and user guides.
Read the architecture document
The admin console permission rules screen: which commands agents may attempt, scoped to which metadata paths
Permission rules: what agents may attempt, scoped to what they may touch. Every impactful command still needs a human approval.

Deployment steps

From clone to first session

Six steps. The first user to register becomes the super admin; everyone after that is pending until an admin approves them.

  1. 1

    Salesforce Connected App

    Once, in any org you control.

    • Setup, App Manager, New Connected App. Enable OAuth settings.
    • Callback URL: https://<your-server>/api/v1/oauth/salesforce/callback
    • Scopes: api, refresh_token and offline_access, web, openid.
    • Enable PKCE. Optionally disable "Require secret for Web Server Flow" and leave the client secret empty.
    • Copy the consumer key and secret into SF_CLIENT_ID and SF_CLIENT_SECRET.

    Each client org is then authorised by an admin clicking Connect to Salesforce in the admin console. The refresh token is stored encrypted. Sandboxes use the test login URL or the My Domain login URL.

  2. 2

    GitHub, per client

    Create a fine-grained personal access token, or a GitHub App installation token, with Contents read/write and Pull requests read/write on the client's SFDX repository, and enter it in the client's GitHub tab. The repository must already contain the SFDX project, by default under force-app/main/default.

  3. 3

    AI providers

    In the admin console as a super admin: AI, Providers, then set a key for any of Anthropic, OpenAI, DeepSeek or DeepInfra. Enable models and bind them to agent roles. DeepSeek and DeepInfra speak the OpenAI protocol and default to their own endpoints, so a key is all they need. Verify the prices in the models table; the spend ceilings use them.

  4. 4

    The server

    Node 22. SQLite on a persistent disk. TLS in front.

    git clone <your fork or the SF Claws repository>cd sf-clawsnpm cinpm run buildcd packages/servercp .env.example .env    # set PUBLIC_URL, MASTER_KEY, JWT_SECRET, SF_CLIENT_ID, SF_CLIENT_SECRET, CORS_ORIGINSNODE_ENV=production node dist/index.js

    Generate the master key with the one-liner below and keep it in a secret manager. Rotating it needs a re-encryption migration, so treat it as permanent.

    node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

    The server serves the admin console from the same origin by default, including the extension pairing page and the OAuth result page. Put it behind TLS (nginx, Caddy, a cloud load balancer or the platform router). Server-sent events need the proxy to leave response buffering off. When a proxy terminates TLS, set TRUST_PROXY=true so the audit log and the rate limiter see the real client address. Back up the data directory: the SQLite file and its write-ahead log.

    Or with Docker

    docker compose up -d --build    # env from packages/server/.env, data in the /data volume

    Environment referencedocker-compose.yml

  5. 5

    The Chrome extension

    Use ours, or publish your own.

    The quickest path is the SF Claws Chrome Extension on the Chrome Web Store. On first run each admin enters your server URL, grants permission for that origin and pairs the device: the panel shows a code, and the admin console approves it. The user must already be approved by the super admin.

    To build and distribute your own, through the Web Store as private or unlisted, or through enterprise policy with ExtensionInstallForcelist:

    npm run build -w @sf-claws/extension# load packages/extension/dist unpacked, or publish packages/extension/release/sf-claws.zip
  6. 6

    First client, first session

    Create a client, connect its org, add its GitHub repository, add the consultants as members, and write its standing instructions: the CLAUDE.md for that client. Link your documentation and product repositories as knowledge sources. Then open a sandbox in Chrome, open the side panel, and ask for something small.

    Admin guideUser guideTenancy and isolation

Community

This only works as a community project

3B built SF Claws for one operations team and one product suite. The Salesforce ecosystem has thousands of products, hundreds of metadata types and dozens of ways to host a Node.js service. Nothing product-specific is compiled in by design, and that leaves a lot of room for the people who know their corner of the platform better than we do.

Model providers

Gemini, Bedrock, Vertex, Azure OpenAI and local runtimes. The provider interface is small and the OpenAI-compatible path already exists.

Skills and playbooks

Markdown skills for common admin work: data model changes, Flow patterns, permission set design, managed package rollouts for specific products.

Metadata coverage

More metadata types with validation feedback, better diff rendering for layouts and Flows, and support for unlocked packages.

Hosting recipes

Tested guides for Heroku, Fly.io, Cloud Run, ECS and Kubernetes, with the reverse proxy and SSE settings each needs.

Tests and evaluations

Scripted provider scenarios that pin agent behaviour, and evaluations that catch a prompt regression before a user does.

Documentation and translations

Admin and user guides in more languages, and worked examples of end-to-end sessions.

How to contribute

  1. Open an issue first for anything beyond a small fix, so the approach is agreed before the work.
  2. Contract changes go into the shared package first, and any schema change is a new migration.
  3. Anything that changes a Salesforce org goes through the approval gate and takes a plain-language reason.
  4. Tests cover the behaviour, not just the happy path. Agent behaviour is pinned with the scripted provider, never a live API.
  5. Before pushing:
npm run lint && npm run typecheck && npm test

Links

Star it, fork it, run it

The repository has everything on this page in more detail, and a CI that runs lint, typecheck and the full test suite on every push.

View on GitHubBack to the introduction