TrustClaw: A Self-Hosted Agent That Trades Local Control for a Managed Tool Surface

The problem TrustClaw picks: an agent with broad tool access but no keys and no shell

Most personal agent projects ask you to paste provider API keys into a local config file and then let the model run commands on the same machine that holds those keys. TrustClaw is positioned as a direct answer to that arrangement. The README frames the comparison in a table titled Security model, contrasting TrustClaw with what it calls vanilla local agents: credentials encrypted and managed by Composio rather than plaintext in local config, code execution in a remote sandbox rather than on your machine, OAuth instead of manual API key setup per app.

The target user is someone who wants a persistent assistant reachable from a web dashboard or Telegram, connected to Gmail, GitHub, Slack, Notion, Linear, Calendar, Drive, Stripe or HubSpot, and who is unwilling to hand that assistant raw credentials or a shell on their laptop. The README states the threat model explicitly: a destructive prompt injection arriving through a scraped email cannot run rm -rf on your laptop because the agent has no shell there.

That is a narrower audience than "anyone who wants an AI assistant". If your tools are not in Composio's catalogue, or if the value you get from an agent comes precisely from it operating on your local filesystem, the security trade at the centre of this project removes the capability you wanted.

How the agent actually runs: prepareAgentRun, ToolLoopAgent, and four backing services

The architecture diagram in the README shows three entry points feeding one Next.js app: the web dashboard, a Telegram bot, and cron. Inside the app sits a tRPC API plus the agent runtime, and the runtime is drawn as a two-stage pipeline, prepareAgentRun into ToolLoopAgent. From there the app fans out to four dependencies: Postgres with pgvector, Redis, the AI Gateway, and Composio.

Each dependency has a defined job. Postgres with pgvector holds long-term memory, so retrieval is a vector search against stored embeddings rather than replaying a transcript. The AI Gateway handles both LLM calls and embedding calls, which is why the README says no Anthropic or OpenAI API keys are required. Composio supplies the tool integrations. Redis is described as optional in the tech stack list and is used for resumable streams, and it also backs the per-user rate limiting described further down the README.

The context management is where the engineering detail sits. The README describes a 3-layer scheme: pruning, memory flush, and summarization compaction, with the stated goal that conversations can run indefinitely. Rather than one truncation strategy, the runtime prunes, writes durable facts out to vector memory, and compacts the remaining history. The README does not publish the thresholds at which each layer triggers, so the practical behaviour of that pipeline is something you would have to read out of the source rather than the documentation.

Getting an instance running: the CLI path, the Vercel template, and the environment variables that matter

The README gives two deployment routes. The Vercel template button clones the repository and prompts for three environment variables: BETTER_AUTH_SECRET, COMPOSIO_API_KEY and CRON_SECRET, with the template description instructing you to generate the two secrets with openssl rand -base64 32 and to obtain a free Composio API key from the Composio dashboard. The same template pulls in Neon for storage and Upstash for KV.

The CLI route is a single command:

npx @composio/trustclaw deploy

The stated prerequisites are a Vercel account with npx vercel login already done, a GitHub account with gh auth login already done, and the Composio API key. Installing the Composio CLI itself is a separate step, curl -fsSL https://composio.dev/install | bash, per the README. The README claims the CLI handles the entire flow and that self-hosting takes roughly two minutes, a number that comes from the project's own documentation and not from any test performed here.

Authentication is username and password through Better Auth. The rate limiting layer ships enabled by default and is controlled by RATE_LIMIT_CHAT_PER_MINUTE, RATE_LIMIT_CHAT_PER_DAY, RATE_LIMIT_CRON_PER_DAY, RATE_LIMIT_TELEGRAM_PER_MINUTE, RATE_LIMIT_FAIL_MODE and RATE_LIMIT_ENABLED. The default for RATE_LIMIT_FAIL_MODE is open in development and closed otherwise, which means a production instance without REDIS_URL will reject agent entrypoint traffic when Redis is unreachable. The README tells you to either configure REDIS_URL or explicitly set RATE_LIMIT_FAIL_MODE=open or RATE_LIMIT_ENABLED=false. That is the first thing to check after a first deploy, because a missing Redis URL presents as a broken agent rather than a configuration warning.

The Vercel Hobby plan quietly changes what your cron jobs can do

This is the sharpest constraint in the README and it deserves to be read before the deploy button, not after. On Vercel's free Hobby plan, cron jobs can run once per day, and the README notes they fire anywhere within a 60-minute window of the scheduled hour. Any expression more frequent than daily, hourly or every thirty minutes for example, fails at deploy time. The CLI works around this by rewriting vercel.json to a daily schedule when it detects Hobby.

So the recurring-task feature, which the README lists as a headline capability under "Works While You Sleep", is materially reduced on the free tier. A daily window that drifts by up to an hour is a different product from per-minute scheduling. The second Hobby limit is a 300s cap per function, and the README warns that long-running agent turns may time out. Vercel Pro raises that to roughly 800s and restores per-minute cron, at which point the README says to re-run the CLI or manually set vercel.json back to * * * * * and raise maxDuration.

The CLI's automatic adjustment is helpful and also slightly opaque: a deploy that silently rewrites your schedule is a behaviour you want to know about in advance. If scheduled work is the reason you are installing TrustClaw, budget for Pro or plan around a daily cadence.

Where TrustClaw is the wrong tool

Three cases stand out. The first is any workflow that depends on the local machine. TrustClaw's security story is built on the agent not having a shell on your laptop, so tasks like reorganising a local directory, driving a desktop application, or reading a local database are outside what this architecture does. Choosing TrustClaw means giving that up deliberately.

The second is tool coverage. The README claims 1000+ Composio integrations and names a set of common SaaS products, but the tool surface is whatever Composio exposes and whatever the user has connected via OAuth. A bespoke internal API, or a service Composio does not cover, has no obvious path in. The README does not describe a mechanism for registering arbitrary custom tools, so treat this as a boundary rather than a gap that is documented as solvable.

The third is multi-tenant exposure. The README's own production checklist says that if you put an instance on the public internet for strangers to sign up to, you should add at least a monthly per-user message and tool-call cap enforced server-side, plus billing or invite-only access. The shipped rate limits are per-minute and per-day counters, not monthly quotas. So the default configuration is sized for a personal or small-team instance, and the README itself says a public signup instance needs more. That is an honest admission and also a warning that the defaults are not a public-service configuration.

The README does not state what happens to in-flight agent turns when a function hits the 300s cap on Hobby, or whether the resumable streams backed by Redis recover the turn. If long turns matter to you, that behaviour is worth confirming in the source before you rely on it.

The alternative: a local agent framework with your own keys and your own shell

The obvious comparison is a local agent framework where you supply provider API keys and the agent executes on your machine. The difference is not a feature checklist, it is where the trust boundary sits. In the local model, the agent's reach equals the permissions of the process running it, and a prompt injection that convinces the model to run a command runs that command with your user's rights. Credentials live in a config file on the same disk.

TrustClaw moves the boundary outward. Tool calls are brokered by Composio over OAuth, so the agent never holds a Gmail or Stripe token directly, and the README lists one-click revocation as a property of that arrangement. Code execution happens in a remote environment that the README says is gone when the task is done. The cost is that you no longer control the execution environment, you depend on Composio's availability and catalogue, and you cannot reach anything that is only on your machine.

Neither model subsumes the other. If your agent's value is acting on local files and local processes, the local framework wins on capability and you accept the risk. If your agent's value is acting on SaaS accounts and running unattended, TrustClaw's arrangement removes a class of failure that the local model cannot remove without significant sandboxing work of your own.

Maintenance surface, licence, and what to verify before you commit

The stack you inherit is broad: Next.js 15 with the App Router and React 19, tRPC for backend logic, Better Auth for username and password login, Prisma against Postgres with pgvector, the Vercel AI SDK plus AI Gateway, the Composio SDK, Tailwind with shadcn/ui, and Redis. Each of those moves on its own release cadence, and Prisma plus pgvector in particular means database migrations are part of your upgrade path. The repository shows no retrieved releases, so there is no published version history to pin against; the last push recorded is 2026-07-10 on the main branch. That is a fact about the repository metadata, not a judgement about the project's health.

The licence is MIT, which permits commercial use and modification with the licence and copyright notice retained in copies or substantial portions. That is a statement about the licence text, not legal advice; if you are embedding this in a product, have counsel read the MIT terms and the terms of the services it depends on, because Composio, Vercel, Neon and Upstash each carry their own agreements that the MIT licence does not touch.

Before deploying, verify the cron expression your Vercel plan will accept, confirm REDIS_URL is set so the fail-closed rate limit default behaves as intended, and check whether your longest agent turn fits inside the 300s Hobby function cap. Those three checks come straight from the README's own production notes, and each one fails in a way that looks like a bug in the agent rather than a limit of the platform underneath it.

Editorial conclusion

Adopt TrustClaw if you want a personal agent whose tool calls are brokered by Composio over OAuth and whose code execution never touches your machine, and you accept Vercel plus a Composio API key as part of the stack. Do not adopt it if you need per-minute cron on the free plan, if your tools are not in Composio's catalogue, or if you want the agent to have a shell on your own hardware. Before deploying, verify three things in your own environment: whether your Vercel plan accepts the cron expression in vercel.json, whether REDIS_URL is set so rate limiting fails closed as the README describes, and whether the Hobby plan's 300s function cap is long enough for your longest agent turn.

Official sources

1. ComposioHQ/trustclaw on GitHub
2. Issues
3. License: MIT
4. README