DOCSEARCHbyAlgolia
Submit Docs

TrustClaw Documentation

repository·main·Indexed 21 days ago

https://github.com/composiohq/trustclaw

A self-hostable personal AI assistant designed for secure, automated task execution. TrustClaw features long-term vector memory, sandboxed remote execution, and over 1000 tool integrations via Composio OAuth. It supports scheduling recurring tasks on autopilot and integrates with Telegram. The project includes a dedicated CLI (@composio/trustclaw) to automate deployment to Vercel, including database provisioning (Postgres + pgvector) and environment configuration.

Tokens
14.6K
Snippets
50
Records
70
Agent score
74%

What's inside TrustClaw

  1. Deploy TrustClaw using the CLI

    main

    You can deploy a full instance of TrustClaw to Vercel using a single command sequence. The @composio/trustclaw CLI automates the entire lifecycle, including forking the repository to your GitHub, creating a Vercel project, provisioning databases (Postgres + pgvector via Vercel Marketplace and optionally Upstash Redis), generating secrets (BETTER_AUTH_SECRET, CRON_SECRET), syncing the Prisma schema, and triggering the production deployment. It also provides guided setup for Telegram bots and Vercel plan tuning.

    git clone https://github.com/ComposioHQ/trustclaw && cd trustclaw
pnpm install
npx @composio/trustclaw deploy

  2. Prerequisites for TrustClaw deployment

    main

    Before running the deployment command, ensure you have the following accounts and tools configured:

    • Vercel Account: You must be logged in via the CLI (npx vercel login).
    • GitHub Account: You must have the GitHub CLI (gh) installed and authenticated (gh auth login).
    • Composio API Key: You need a free API key from the Composio Dashboard.

  3. Deploy TrustClaw via Vercel or CLI

    main

    You can deploy your own instance of TrustClaw in approximately 2 minutes using either the Vercel template or the official CLI.

    Option 1: Vercel Template

    Click the Deploy with Vercel button to clone the repository and deploy it to your Vercel account. This method automatically configures necessary integrations like Neon (Postgres) and Upstash (KV).

    Option 2: CLI Deployment

    Use the @composio/trustclaw CLI to handle the entire deployment flow.

    Prerequisites:

    Note: LLM and embedding calls route through Vercel AI Gateway, so no Anthropic or OpenAI API keys are required.

    npx @composio/trustclaw deploy

  4. Set up TrustClaw for local development

    main

    To run TrustClaw locally for development, follow these steps:

    1. Install dependencies using pnpm.
    2. Create a .env file from the template and populate it with your credentials.
    3. Push the database schema to a Postgres instance with pgvector support.
    4. Start the development server.

    Note for AI Gateway: For local access to the AI Gateway, run vercel link && vercel env pull to obtain a short-lived OIDC token, or set AI_GATEWAY_API_KEY manually.

    Note for Telegram: Point your bot's webhook to <NEXT_PUBLIC_APP_URL>/api/telegram-webhook using TELEGRAM_WEBHOOK_SECRET as the secret token.

    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

  5. Configure rate limiting and usage caps

    main

    TrustClaw includes Redis-backed per-user rate limiting for chat, cron, and Telegram entrypoints. These are enabled by default.

    Rate Limit Variables

    • RATE_LIMIT_CHAT_PER_MINUTE / RATE_LIMIT_CHAT_PER_DAY
    • RATE_LIMIT_CRON_PER_DAY
    • RATE_LIMIT_TELEGRAM_PER_MINUTE
    • RATE_LIMIT_FAIL_MODE: Set to open in development; otherwise defaults to closed.
    • RATE_LIMIT_ENABLED: Set to false to bypass all agent entrypoint limits.

    Production Considerations

    • Redis: In production, ensure REDIS_URL is configured.
    • Public Access: If exposing TrustClaw to the public internet, implement additional server-side caps for messages and tool calls to manage costs.

  6. Redis configuration logic

    main

    During the setup process, the CLI determines whether to provision Upstash Redis for resumable streams based on existing environment variables.

    • If REDIS_URL or KV_URL is already present in the project's environment keys, the CLI will automatically reuse the existing connection and skip the prompt.
    • Otherwise, you will be prompted to Add Upstash Redis for resumable streams? (recommended).

    Note: Composio is resolved automatically from the local Composio CLI, and stores are provisioned via vercel integration add without additional user prompts.

  7. Configure TrustClaw environment variables

    main

    TrustClaw requires several environment variables for operation. If you are performing a manual setup, ensure the following are configured in your .env file.

    VariablePurpose
    DATABASE_URLPostgres + pgvector connection string
    BETTER_AUTH_SECRETSession signing key (32+ random bytes)
    COMPOSIO_API_KEYComposio tool integrations
    CRON_SECRETAuth for /api/cron/* routes (auto-injected on Vercel)
    REDIS_URL(optional) Resumable streams + abort flags
    TELEGRAM_BOT_TOKEN(optional) Telegram bot token
    TELEGRAM_BOT_USERNAME(optional) Telegram bot username
    TELEGRAM_WEBHOOK_SECRET(optional) Telegram webhook auth

    Tip: You can generate BETTER_AUTH_SECRET and CRON_SECRET using: openssl rand -base64 32.

  8. Understand the TrustClaw tRPC context and error formatting

    main

    The tRPC instance in TrustClaw is configured with the following behaviors:

    • Context: The context includes headers and the current session (retrieved via auth.api.getSession).
    • Transformer: Uses superjson for efficient data serialization/deserialization.
    • SSE (Server-Sent Events): Configured for long-lived connections with a maxDurationMs of 50,000 (to prevent Vercel timeout issues), a ping interval of 15,000ms, and a client reconnection interval of 20,000ms after inactivity.
    • Error Formatting: If a ZodError occurs during validation, the error response is automatically flattened and included in the zodError field of the error data, making it easier for clients to parse validation failures.

  9. Deploy TrustClaw via CLI

    main

    The deploy command automates the end-to-end deployment of a TrustClaw instance. It handles GitHub repository forking (or local publishing), Vercel project creation, provisioning of data stores (including optional Redis), environment variable configuration (including COMPOSIO_API_KEY), database migrations via Prisma, and Telegram webhook setup.

    Deployment Workflow:

    1. Authentication: Detects Vercel and GitHub credentials.
    2. Project Setup: Creates or reuses a Vercel project and disables deployment protection to allow external webhooks (like Telegram) to function.
    3. Repository Management: Either forks the official repository to a new GitHub repo or publishes your local repository changes.
    4. Infrastructure: Provisions required stores and sets environment variables.
    5. Database: Runs migrations against the provisioned database.
    6. Deployment: Triggers a production deployment on Vercel.
    7. Webhooks: Configures Telegram using the stable Vercel production alias to ensure webhook persistence across redeploys.

    Note: Cron jobs are pre-configured in vercel.json and will run automatically once the deployment completes. You can monitor them in the Vercel dashboard under the 'Cron Jobs' tab.

    trustclaw deploy

  11. Integrate tRPC React hooks and provider

    main

    To use tRPC in a React application within the TrustClaw ecosystem, wrap your application with the TRPCReactProvider. This provider sets up the necessary QueryClientProvider and the tRPC client with httpBatchStreamLink and SuperJSON for data transformation.

    Once wrapped, you can use the exported api object to access tRPC hooks (like api.useQuery or api.useMutation) throughout your component tree. The client is configured to communicate with the /api/trpc endpoint and includes a loggerLink that is active in development mode or when errors occur in production.

    import { TRPCReactProvider, api } from "./path-to-this-file";

function App() {
  return (
    <TRPCReactProvider>
      <MyComponent />
    </TRPCReactProvider>
  );
}

function MyComponent() {
  // Use the api object to call procedures
  const hello = api.example.hello.useQuery({ text: "world" });
  return <div>{hello.data?.greeting}</div>;
}

  12. Set up a Telegram bot for TrustClaw

    main

    The TrustClaw CLI provides a utility to automatically configure a Telegram bot, allowing you to chat with your agent from your phone. The setup process involves:

    1. Obtaining a Bot Token: Use @BotFather on Telegram to create a new bot via the /newbot command. You will receive a token in the format 1234567:ABC-DEF....
    2. Providing Bot Details: The CLI will prompt you for the bot token and the bot's username (without the @).
    3. Automated Configuration: The utility automatically sets the following environment variables on your Vercel project:
      • TELEGRAM_BOT_TOKEN
      • TELEGRAM_BOT_USERNAME
      • TELEGRAM_WEBHOOK_SECRET (generated automatically)
    4. Webhook Registration: The utility registers a webhook with Telegram pointing to https://<your-deployment-url>/api/telegram-webhook.
    5. Redeployment: To ensure the new environment variables are active, the CLI triggers a fresh production deployment on Vercel.

    If the automated webhook registration fails, you can register it manually using curl.

    # Manual webhook registration if automated setup fails:
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
     -d "url=https://<your-deployment-url>/api/telegram-webhook&secret_token=<SECRET>"