TrustClaw Deployment and Security Guide

trustclaw GitHub tool guide thumbnail

TL;DR

TL;DR: trustclaw is a self-hosted personal AI agent for recurring work: Next.js dashboard, Telegram access, Composio OAuth tools, Postgres/pgvector memory, Vercel AI Gateway models, and sandboxed execution instead of local shell access.

Source and Accuracy Notes

This article uses official project material from ComposioHQ/trustclaw, especially the root README and repo architecture notes. Commands below are limited to commands documented by the project. When a workflow detail is not explicit, this guide calls out the gap rather than filling it with guessed package-manager steps.

The repo describes trustclaw as a security-first rebuild inspired by OpenClaw. Current setup is strongly shaped by Vercel, Neon/Postgres with pgvector, Upstash KV, Composio, Better Auth, tRPC, Prisma, and Vercel AI Gateway. That combination matters: trustclaw is not a generic local CLI agent. It is a hosted web app whose agent runtime, memory, auth, cron, integrations, and chat surfaces are tied together.

What Is trustclaw?

trustclaw is a 24/7 personal AI assistant that can chat through a Next.js web dashboard or Telegram, remember useful context, connect to third-party services through OAuth, and run recurring tasks on a schedule. Its central promise is not only “AI agent with tools.” Its promise is safer agency: actions go through Composio-managed OAuth integrations and execute in isolated cloud environments instead of handing a local agent long-lived credentials and shell access on your laptop.

Architecture is repo-specific. Frontend and backend live in one Next.js app. Backend logic runs through tRPC procedures under the app, auth uses Better Auth with username/password login, data sits in Postgres with vector search, and long-running context uses a three-layer strategy: pruning, memory flush, and summarization compaction. Model and embedding calls route through Vercel AI Gateway, which reduces direct OpenAI or Anthropic key handling for normal Vercel deployments.

The interesting part for runany.dev readers is operational fit. trustclaw is not best when you need a throwaway terminal copilot. It is better when you want a small personal agent service: “every morning summarize my calendar and email,” “watch GitHub issues,” “draft follow-ups,” “run a scheduled task,” or “interact with connected SaaS accounts without pasting API tokens into .env files per tool.”

Repo-Specific Setup Workflow

Step 1: Choose Vercel template or CLI deployment

Fastest path is the Vercel template button from the project page. It preselects the TrustClaw repo, asks for required env vars, and offers Neon and Upstash integrations. If you prefer terminal flow, use the documented CLI path:

npx @composio/trustclaw deploy

That command is the repo’s intended “one command” deploy path. Treat it as the primary installer, not git clone plus improvised scripts.

Step 2: Prepare required accounts and keys

The documented prerequisites are Vercel login, GitHub CLI login, and a Composio API key. These exact commands appear as one-time prerequisite checks:

npx vercel login

gh auth login

The README also points users to the Composio CLI install command when getting a free API key:

curl -fsSL https://composio.dev/install | bash

For secrets, the Vercel template text instructs users to generate BETTER_AUTH_SECRET and CRON_SECRET like this:

openssl rand -base64 32

Step 3: Understand required runtime services

trustclaw needs DATABASE_URL, BETTER_AUTH_SECRET, COMPOSIO_API_KEY, and CRON_SECRET. DATABASE_URL must point to Postgres with pgvector because long-term memory depends on vector storage. COMPOSIO_API_KEY is server-side; Composio brokers integrations and OAuth-connected tool calls. CRON_SECRET protects /api/cron/* routes.

Local AI Gateway access has two official options: link/pull Vercel env for a short-lived OIDC token, or set AI_GATEWAY_API_KEY manually. The exact phrase in docs is command-shaped:

vercel link && vercel env pull

Step 4: Run local development only with documented commands

For local work, the project provides a short path:

pnpm install
cp .env.example .env       # fill in DATABASE_URL, BETTER_AUTH_SECRET, COMPOSIO_API_KEY
pnpm prisma db push        # apply schema (Postgres + pgvector required)
pnpm dev                   # http://localhost:3000

Repo notes also list maintenance commands:

pnpm build
pnpm lint
pnpm auth:generate

These commands reveal real stack boundaries: package install, Prisma schema push, Next dev server, production build, lint, and Better Auth client type generation.

Step 5: Plan Vercel tier around cron expectations

Hobby deployments have meaningful cron limits. The project notes daily-only cron behavior and a window around scheduled time; the CLI adjusts vercel.json to a daily schedule when it detects Hobby. If your use case needs per-minute recurring work or longer function duration, Vercel Pro is the practical deployment target.

Deeper Analysis

trustclaw’s design reduces several common agent hazards. First, OAuth replaces direct password/API-key sharing for third-party tools. Second, sandboxed remote execution narrows blast radius compared with a local agent that can read arbitrary home-directory files. Third, audit trails and revocation become visible features instead of “delete secret from random config file and hope.”

The tradeoff is dependency concentration. You get secure defaults by accepting Vercel, Composio, Postgres/pgvector, Upstash, and AI Gateway as core pieces. That is reasonable for a personal hosted assistant, but it is not minimal. If you want offline local inference, this repo is a mismatch. If you want recurring web/SaaS work with hosted auth and low setup friction, it is well aligned.

Repo architecture is also unusually production-minded for an agent demo. Better Auth handles username/password login; tRPC keeps backend contracts typed; Prisma owns schema state; memory is not pasted into prompts forever but periodically pruned and compacted; tool calls happen server-side behind one COMPOSIO_API_KEY. Those are sensible boundaries for an app that may see email, calendars, GitHub repos, tickets, and private notes.

The biggest evaluation question is “who owns the actions?” trustclaw still performs AI-directed work against real accounts. OAuth scopes, Composio app connections, cron frequency, and prompt-injection resistance need review before connecting sensitive apps.

Practical Evaluation Checklist

Confirm your target tasks are recurring or integration-heavy, not one-off local code edits.
Confirm Postgres includes pgvector; memory features depend on vector storage.
Decide whether Vercel Hobby cron limits are acceptable before relying on automation.
Use separate test OAuth accounts before connecting primary Gmail, GitHub, Slack, or Drive.
Review Composio tool scopes and revoke unused integrations early.
Keep BETTER_AUTH_SECRET, CRON_SECRET, DATABASE_URL, and COMPOSIO_API_KEY server-side only.
Test Telegram separately from web chat; they are different interaction surfaces.
Run local pnpm lint and pnpm build before changing auth, cron, memory, or agent runtime.

Security Notes

trustclaw’s security model is its main differentiator, but “safer” does not mean “risk-free.” OAuth can still grant broad permissions. A sandbox can still perform damaging remote actions through allowed tools. Cron can repeat a bad instruction. Memory can persist sensitive facts. Treat first deployment like a staging agent, not an invisible employee.

Protect /api/cron/* with CRON_SECRET, avoid exposing local .env, rotate Composio keys if they leak, and prefer least-privilege OAuth scopes. If you self-host for a team, add rate limiting at chat and cron endpoints as the project suggests. For work accounts, audit action logs and start with read-only integrations when possible.

FAQ

Q: Is trustclaw a local coding agent? A: No. It is a self-hosted web/Telegram personal assistant. Its repo emphasizes OAuth integrations, cloud sandbox execution, memory, cron, and hosted deployment.

Q: Do I need OpenAI or Anthropic API keys? A: Normal Vercel deployment routes LLM and embedding calls through Vercel AI Gateway, so direct provider keys are not the central setup path.

Q: Can Vercel Hobby run frequent scheduled tasks? A: No. Hobby cron behavior is limited. For per-minute precision and longer function duration, plan for Vercel Pro.

Q: What should I test first? A: Deploy with a test user, connect one low-risk Composio integration, create a simple scheduled task, then inspect logs and revocation flow.

Conclusion

trustclaw is worth watching because it treats agent security as architecture, not marketing copy. Its best use case is a personal hosted assistant that can remember, schedule, and act across OAuth-connected services without storing passwords or running arbitrary shell commands on your machine. Use the documented Vercel/CLI path, respect cron limits, and evaluate integrations one scope at a time.