# Welcome to Calvin AI-powered operational copilots for eCommerce teams Calvin is an AI-powered platform that adds operational capacity to your eCommerce team. It provides specialized AI agents trained in real eCommerce roles — development, QA, design, analytics, and more — that turn tasks that used to take hours into executions that take minutes. You describe what you need in natural language. Calvin's agents understand, plan, execute, and deliver results for your review. No complex briefs, no extra headcount, no technical friction. Calvin is a product of Gopersonal, backed by 500 Startups. ### Jump right in

:bolt:

Getting StartedYour first steps in Calvin./pages/fjfZsFmNFVrJDgqLlBML

:book:

User GuideLearn how to use, create and maintain your agents squad./pages/6CeKcJMWOcMSK0RcIPlG

:code:

Developer GuideLearn how to set up your environment and integrate with 3rd party tools./pages/Gi8eXISOEowUW3mv2ISK
# What is Calvin? **Calvin** is an AI-powered multi-agent platform designed for eCommerce.\ It brings together specialized agents that handle the full lifecycle of your digital operations — from **development, testing, and maintenance**, to **personalization, marketing, analytics, and customer support**. Calvin includes a library of **predefined agents**, each optimized for a specific area of eCommerce, such as: * **Development agents** that help build and deploy new features. * **Testing agents** that automate QA and ensure reliability. * **Maintenance agents** that monitor uptime and performance. * **Marketing agents** that personalize campaigns and content. * **Personalization agents** that tailor recommendations, experiences, and interactions. * **Analytics agents** that uncover insights and trends. * **Support agents** that enhance post-purchase experiences. In addition, Calvin allows the creation of **custom agents** that can be fully tailored to unique business needs, processes, and tools — enabling every team to extend and adapt the platform to their workflow. # Why Calvin? Because running a modern eCommerce operation means juggling dozens of moving parts — and Calvin connects them all. * 🧠 **Unified intelligence** — agents collaborate and share context across domains. * ⚙️ **Automation with control** — repetitive tasks handled by AI, with human oversight. * 💡 **Personalization at scale** — deliver unique, data-driven experiences for every customer. * 🚀 **Scalable by design** — start with one agent, expand into a full AI-powered team. * 🔄 **Adaptive learning** — agents continuously improve from performance data and feedback. * 🌐 **Seamless integration** — connect Calvin with your existing tools, APIs, and platforms. With Calvin, your eCommerce ecosystem becomes a living, learning environment — where intelligent agents work side by side with your team to build, personalize, and scale every part of your digital experience. # Key Concepts Before diving into Calvin, it helps to understand the key concepts that make up the platform. These terms appear throughout the documentation and the product itself. #### **Store** A Store is your organization's top-level account in Calvin. It contains all your workspaces, agents, team members, billing, and settings. Think of it as your company's Calvin instance. #### **Workspace** A Workspace is a self-contained development environment where Calvin's agents do their work. Each workspace is tied to a specific technology stack (e.g., Node.js/Next.js, VTEX IO, Magento, Shopify) and comes pre-configured with the right agents for that stack. Workspaces include a code editor, file explorer, browser preview, version control, and a chat interface where you interact with agents. #### **Agents** Agents are the AI copilots that execute tasks inside workspaces. Calvin comes with built-in agents specialized in different roles (Full Stack Developer, Analyst, UI/UX Specialist, Web QA Specialist, and others), each belonging to a team and assigned a seniority level. You can also create Custom Agents with their own knowledge base for specialized workflows. #### **Knowledge** Knowledge represents the information and context that agents use to make decisions, generate content, and execute tasks effectively.\ It can include documentation, style guides, FAQs, business rules, or any other structured or unstructured data relevant to the Store or Workspace. #### **Chat** A Chat is a single task session within a workspace. You create a chat by describing what you want Calvin to do, and the agent creates a plan, executes it step by step, and delivers the result. Each chat operates on its own Git branch and produces a worklog of everything that was done. Chats have lifecycle statuses: Working, Completed, or Discarded. #### **Blocks** Blocks are infrastructure components and knowledge packs you can add to a workspace. Building Blocks provide services like databases, AI SDKs, error tracking, image processing, and object storage. Skills are community-contributed knowledge packs (like React best practices or TypeScript patterns) that enhance how agents work within a specific technology. #### **Connectors** Connectors are MCP (Model Context Protocol) integrations that extend a workspace's capabilities by connecting it to external services and tools. #### **Tips** Tips are curated knowledge entries that guide how agents behave. You can create tips manually to teach Calvin your team's preferences, coding standards, or workflow patterns. Tips can be targeted to specific workspaces or workspace types. #### **Memory** Memory is Calvin's automatic learning system. When a chat is completed, Calvin extracts learnings from the session and proposes them as memories. You confirm which memories to keep, and Calvin applies them to future tasks — getting smarter with every interaction. #### **Artifacts** Artifacts are outputs generated by workspaces (such as code components, reports, or design assets) that can be shared across your team. They can be public, private, or shared with specific team members. #### **Builder & Runtime** Builder and Runtime are the two cost dimensions in Calvin. Builder credits are consumed when agents are actively working on tasks (the AI execution time). Runtime credits are consumed by deployed applications and their infrastructure — compute, databases, storage, and other resources running on Calvin's hosting. # Overview The **User Guide** provides a high-level view of how to use Calvin to manage, train, and coordinate agents within an eCommerce environment. Its purpose is to help users understand the main features, workflows, and best practices to make the most of the platform. Throughout this guide, you will learn how to: * Set up and manage a **Store**, the container for your projects, data, and configurations. * Create and organize **Workspaces**, where human teams and agents collaborate to develop, design, test, or personalize different areas of your eCommerce operations. * Interact with agents via **Chat**, using natural language instructions to execute tasks or retrieve information. * Train and monitor agents’ **Knowledge** and complement it with **Tips** and **Memory**. * Create and deploy complex systems using **Blocks** and **Connectors.** * Monitor metrics, performance, and progress across different areas. The main goal of this guide is to help each user — whether from business, technical, or creative roles — integrate into the AI-driven workflows and optimize end-to-end eCommerce processes. # First Steps Set up your Store and run your first task in minutes This guide walks you through your first experience with Calvin, from logging in to getting your first task completed by an AI agent. Once your account is created, you land on the Home dashboard. This is your operational hub — it shows your total workspaces, working chats, active agents, and execution time for the current period. You will also find quick actions for navigating to Workspaces, Agents, Chats, and Usage Analytics, along with your most recent workspaces and any draft tips awaiting review. Your first step is to create a workspace. Click "Add New Workspace" from the Workspaces page or from the Quick Actions on the dashboard. Calvin presents you with a template gallery organized by technology stack. If you work with VTEX, Shopify, Magento, WooCommerce, or any other supported platform, pick the matching template — it will pre-configure the workspace with the right agents and environment. If your use case does not match any template, choose "Start from Scratch" to create a custom workspace and add your own agents. After selecting a template, Calvin provisions your workspace. This includes setting up a development environment, initializing version control, and assigning the appropriate agents. The process takes a few moments. Once inside the workspace, you will see three main areas: the chat panel on the left, the code editor and file explorer in the center, and the browser preview on the right. The top toolbar gives you access to Connectors, Blocks, version history, and the Deploy button. To give Calvin its first task, click the "+" button next to the workspace name to create a new chat. Give the chat a name, describe the task you want accomplished in natural language (for example, "Create a responsive hero section with a promotional banner"), and optionally attach reference files like design mockups or screenshots. If you want Calvin to present a plan before executing, check the "Create plan first" option. Once you submit, the assigned agent analyzes your request, creates a plan with clear steps, and begins executing. You can watch the progress in real time as the agent writes code, creates files, and builds out the solution. When the agent finishes, review the result in the browser preview, check the code in the editor, and either continue the conversation to request adjustments or mark the chat as complete. When a chat is completed, Calvin proposes memories extracted from the session — lessons learned about your preferences, your codebase, and your workflow. Confirm the ones that are relevant, and Calvin will apply them to future tasks automatically. # Navigation Calvin’s interface is designed to provide easy access to all key areas of the platform. Understanding the main navigation elements will help users move efficiently between Stores, Workspaces, and agents. #### **Login** Access Calvin through the secure [login page](https://build.calvincode.ai/auth/login). * Enter your credentials to authenticate. * Upon successful login, you will be directed to the **Store Selector**.
#### Store Selector The **Store Selector** allows users to choose which Store they want to work in. Each Store represents a separate eCommerce project with its own data, agents, and configurations. * **Select an existing Store** from the list to enter its environment. * **Create a new Store** directly from the selector if you have the required permissions. * Stores provide a clear boundary for data, agents, and workflows, keeping operations organized and secure.
> Tip: Users with access to multiple Stores can switch between them seamlessly via the Store Selector. #### Profile The **Profile** can be accessed from the **top-right corner** of the Calvin interface. Clicking on your avatar or name opens the Profile menu, where you can manage personal settings. # Home The **Home** section is the central dashboard of Calvin. It provides a real-time overview of what’s happening across your Workspaces, Agents, and ongoing Chats. From here, users can monitor activity, access key shortcuts, and quickly navigate to the most relevant areas of the platform.
At the top of the dashboard, Calvin summarizes the current status of their AI agents and workspaces.\ This area displays key metrics, including: * **Total Workspaces** – the number of active workspaces in your Store. * **Working Chats** – the number of ongoing chat sessions between agents and users. * **Agents** – the total number of active agents within the Store. * **Execution Time** – the cumulative processing time spent by agents during the current month. These metrics provide an instant snapshot of your Store’s performance and agent activity. #### Chat Status Overview The **Chat Status Overview** displays the distribution of chat states: * 🟡 **Working** – chats currently active. * 🟢 **Completed** – chats successfully finished. * 🔴 **Discarded** – chats manually stopped or marked as irrelevant. It also shows the **Completion Rate**, helping to track how efficiently agents are completing tasks. #### Quick Actions The **Quick Actions** panel allows fast access to the most commonly used areas of the platform: * **Workspaces** – view or create new workspaces. * **Agents** – manage existing agents or deploy new ones. * **Chats** – open or monitor active conversations. * **Usage Analytics** – review activity metrics and performance reports. This section simplifies navigation and accelerates daily operations. #### Recent Workspaces The **Recent Workspaces** section lists the last accessed or modified workspaces for quick navigation.\ Each entry shows: * The workspace name. * The number of agents assigned to it. * A direct link to open it. This provides an efficient way to resume work without searching across multiple pages. #### Draft Tips The **Draft Tips** panel shows suggested or in-progress tips that can be added to agents to improve their knowledge or performance.\ Each tip can be previewed, edited, or published directly from this view, making it easy to continuously refine agent behavior. #### Invite Your Team The **Invite Your Team** module allows you to add new collaborators to your Store.\ Simply enter an email address, select a role (e.g., **Member**, **Admin**), and click **Invite** to send the invitation.\ Inviting teammates enhances collaboration by enabling shared access to workspaces and agents. # Workspaces Workspaces are the core of Calvin. Each workspace is a fully provisioned development environment where AI agents build, modify, and maintain your projects. A workspace combines a code editor, file system, browser preview, version control, and a conversational interface — all in one place. Every workspace is tied to a specific technology stack and comes with agents trained for that stack. When you create a workspace from a template, Calvin automatically assigns the right agents and configures the environment accordingly. Calvin offers workspace templates for a wide range of eCommerce platforms and technologies. For eCommerce platforms, you can choose from Web Development with Node.js and Next.js, VTEX IO Theme development, VTEX IO Apps development, VTEX Admin Development, VTEX FastStore Development, Magento Development, Shopify Development, WooCommerce Development, and Medusa Development. For general development, templates are available for Ruby on Rails, Java Spring Boot, Python with FastAPI, and Mobile App Development. Specialized templates include UI/UX Design, n8n Workflow Automation, Data Science, and Web QA. You can also start from scratch with a blank workspace and assign custom agents. Each template pre-assigns agents from the appropriate team. For example, a Web Development workspace includes a Full Stack Developer and an Analyst, while a Magento workspace includes a Magento Developer and an Analyst. The workspace interface is divided into three main panels. On the left is the chat panel where you interact with Calvin's agents through natural language. Chats are listed by name and status, and you can switch between multiple chats within the same workspace. In the center is the code panel with a file explorer on the left side and a code editor on the right. You can browse the project file tree, open and edit files directly, and view an agents.md file that contains agent configuration. The icons above the file explorer provide access to different views: the file tree, documents, Git controls (View Tree, Tools, and Take over), and workspace configuration settings. On the right is the browser preview panel that renders your application in real time, so you can see changes as the agent makes them. The top toolbar provides access to several important features. The Connectors button opens a panel where you can add MCP integrations to extend the workspace. The Blocks button opens the Blocks Marketplace where you can install building blocks (databases, AI SDKs, error tracking, and more) and skills (community knowledge packs). The version selector shows all saved versions of your workspace and lets you switch between them. The Deploy button initiates the deployment flow to ship your project to production. The three-dot menu at the top right of the workspace provides additional options including Open App (to view your deployed application), Traffic monitoring, Web Analytics, and Web Performance metrics. Workspace configuration is accessible through the settings icon in the file explorer toolbar. This is where you configure source code management, choosing between Calvin's Internal Git (which creates and manages a private repository for you), or connecting your own repository on GitHub, Bitbucket, or GitLab. You can set the target branch that feature branches merge into (such as main, develop, or staging), associate documentation with the project, and configure the chat closing action — either Merge and Push (which automatically merges changes to the target branch when a chat is completed) or Create Pull Request (which opens a PR for your team to review before merging). # Agents Agents are the AI copilots that power Calvin. Each agent is specialized in a particular role, belongs to a team, and has an assigned seniority level that reflects its depth of expertise. The Agents page shows your full squad — both Calvin's built-in agents and any custom agents you have created. Calvin ships with nine built-in agents organized across three teams. The Core Development Team includes the Full Stack Developer (Senior), who executes technical changes, fixes, and builds components across the full stack; the Analyst (Mid), who analyzes data, generates insights, and produces reports; the VTEX IO Developer for Theme (Mid), specialized in building and maintaining VTEX IO storefronts; the Magento Developer (Senior), focused on Magento eCommerce development; the Ruby on Rails Developer (Senior), for building and maintaining systems in Ruby on Rails; the Web QA Specialist (Junior), who detects errors, runs validations, and ensures quality before publishing; and the n8n Workflow Developer (Senior), for building automation workflows with n8n. The Creative Team includes the UI/UX Specialist (Senior), who resolves design tasks and UI adjustments without blocking the rest of the team. The Analytics Team includes the Data Scientist (Senior), who builds ML models and analytics pipelines for eCommerce insights. Seniority levels reflect the agent's depth of knowledge and autonomy. Senior agents have the broadest knowledge and can handle complex, ambiguous tasks with minimal guidance. Mid-level agents are strong in their domain but may need clearer instructions for edge cases. Junior agents are effective for well-defined, repeatable tasks and are great for high-volume QA and validation work. When you create a workspace from a template, Calvin automatically assigns the appropriate agents. For example, a Web Development workspace gets a Full Stack Developer and an Analyst, while a UI/UX Design workspace gets a UI/UX Specialist. Beyond the built-in agents, you can create Custom Agents tailored to your specific workflows. Click "+ Custom Agent" on the Agents page to open the creation dialog. The Info tab asks for an Agent Name, a Description (up to 512 characters explaining the agent's purpose), and a Mission and Goal (defining what the agent should accomplish). The Knowledge tab lets you upload files and instructions that help the agent perform better — for example, your brand guidelines, coding standards, API documentation, or product catalog specifications. Custom agents appear in the Custom Agents section on the Agents page, tagged as "Custom." You can assign them to workspaces alongside or instead of the built-in agents. This is powerful for creating agents that understand your specific business processes, like a "Variant Creator" that generates product variants following your catalog rules, or a "Code Reviewer" that checks pull requests against your team's standards. # Chats How you interact with Calvin's agents to get work done Chats are the primary way you communicate with Calvin's agents. Each chat represents a single task or objective within a workspace. You describe what you need, the agent plans and executes, and you review the result — all through a conversational interface. To create a new chat, click the "+" button next to the workspace name at the top of the chat panel. The New Chat dialog asks for a name (to help you identify the task later), a task description (where you describe what you want Calvin to do in natural language), and optional attachments such as design mockups, screenshots, or reference documents. Under Advanced Options, you can set a custom branch name for the chat session. By default, Calvin creates a feature branch automatically, but you can specify your own naming convention if you prefer. You can also enable Epic mode, which allows the agent to run for a longer period with greater accuracy — ideal for complex, multi-step tasks that require deeper analysis and more thorough execution. The "Create plan first" checkbox tells Calvin to present a detailed plan before starting any work. This is useful when you want to review and approve the approach before the agent begins executing. When this option is enabled, the agent will outline its plan with numbered steps and wait for your confirmation before proceeding. Once a chat is submitted, the agent begins working. You will see a Plan section appear in the chat showing each step and its status (Completed, In Progress, or Pending). Below the plan, a Worklog section is available that you can expand to see the detailed actions the agent took — files created, code written, commands run, and decisions made. You can continue the conversation at any time by typing in the chat input at the bottom of the panel. Ask for adjustments, request changes, or give the agent additional instructions. The "+" button next to the chat input provides quick access to add an Attachment, a Tip (to guide the agent's behavior), a Block (to install infrastructure), an Agent (to bring in a different specialist), a Connector (to integrate an external service), or an Artifact (to reference a previously shared output). Each chat has a lifecycle with three possible statuses. Working means the chat is active and the agent is either executing or waiting for your input. Completed means the task is finished and changes have been merged or a pull request has been created, depending on your workspace configuration. Discarded means the chat was abandoned without applying its changes. You manage chats through the three-dot menu next to the chat name. Complete Chat marks the task as done and triggers the configured chat closing action (merge and push, or create pull request). Export Chat saves the conversation and worklog for reference. Transfer Chat reassigns the chat to a different team member. Discard Chat abandons the chat without applying changes. Delete Chat permanently removes the chat. You can also assign chats to team members. The owner badge next to the chat name shows who is currently responsible for the task. Click the dropdown next to the workspace name to see all chats in the workspace, filtered by status and assignee. # Blocks Marketplace Infrastructure services and knowledge packs for your workspaces The Blocks Marketplace lets you extend your workspace with infrastructure services and knowledge packs. You can access it by clicking the Blocks button in the workspace toolbar, or by selecting "Add Block" from the "+" menu in the chat input. The marketplace is organized into two categories: Building Blocks and Skills. Building Blocks are infrastructure components that add real services to your workspace. Each block runs as part of your workspace environment and may require environment variables to configure. The available building blocks include ai-sdk, which provides access to AI model providers like Vercel AI SDK and LLM integrations and requires three environment variables; database, which provisions a PostgreSQL/SQL database for your application and requires one environment variable; error-tracking, which integrates Sentry for monitoring and error tracking and requires one environment variable; generative-image, which adds AI image generation capabilities powered by Gemini and requires one environment variable; google-search, which enables programmatic Google Search access via API and requires one environment variable; image, which provides image processing capabilities including background removal via Photoroom and requires one environment variable; object-storage, which adds cloud object storage for files and assets; and trigger, which enables automation triggers for event-driven workflows. When you install a building block, Calvin adds the necessary dependencies and configuration to your project. The agent can then use these services when executing tasks — for example, if you have the database block installed and ask Calvin to add a product listing feature, it can create the database schema, write the queries, and wire up the API automatically. Skills are community-contributed knowledge packs that enhance how agents work with specific technologies. Unlike building blocks, skills do not add infrastructure — they add expertise. Skills teach the agent best practices, patterns, and conventions for a particular technology or framework. You can search for skills by technology name. For example, searching for "react" reveals skills like vercel-react-best-practices (with over 117K installs), react:components, react-native-best-practices, react-state-management, react-email, and react-modernization, among others. Each skill shows its install count, helping you gauge community adoption. Skills are particularly valuable because they keep your agents up to date with the latest conventions and patterns for your stack. Installing a Next.js skill, for example, ensures the agent follows current best practices for routing, data fetching, and server components when building your application. You can also add blocks directly from within a chat by clicking the "+" button next to the chat input and selecting "Add Block." This is convenient when you are mid-task and realize you need a new capability. # Connectors Extend your workspaces with MCP integrations Connectors are MCP (Model Context Protocol) integrations that extend what Calvin's agents can do within a workspace. While Blocks add infrastructure and skills to the workspace itself, Connectors bridge the gap between Calvin and your external tools, services, and data sources. You can manage connectors at the workspace level through the Connectors button in the workspace toolbar, or from the workspace list page using the plug icon on each workspace card. You can also add a connector during a chat session through the "+" menu in the chat input. When you click the Connectors button inside a workspace, a panel opens showing all connectors currently configured for that workspace. From here you can view existing connections, add new ones, or remove connectors you no longer need. Each connector extends the agent's capabilities by giving it access to additional tools and data that it can use when executing tasks. Connectors follow the MCP standard, which means they provide a standardized interface for AI agents to interact with external systems. This makes it possible for Calvin's agents to read from and write to external services as part of their normal task execution — without you needing to write custom integration code. # Figma The Figma connector is useful to import Figma designs into the UI/UX workspace or to work with Figma directly from a dev workspace. It is recommended to use it from designs as it is easier to iterate. Before configuring the Figma connector, you will need to obtain a Figma personal access token. Follow the steps below to generate one from your Figma account settings. ### Generating a Personal Access Token 1. Open Figma and click on your profile icon in the top-left corner. From the dropdown menu, select Settings.
2. In the Settings panel, navigate to the Security tab. Scroll down to the Personal access tokens section and click Generate new token. Copy the generated token and keep it safe — you will need it to configure the Figma connector. # google analytics Setting up Google Analytics 4 integration with Calvin Code is straightforward and user-friendly. ## Simple Setup Process The GA4 integration process is very simple: 1. **Access the Link**: A link will be provided in the Calvin Code UI 2. **Google Login**: Click the link and login with your Google account 3. **Select Project**: Choose your GA4 project from the dropdown menu 4. **Complete**: The integration will be automatically configured ## Requirements * Active Google account with access to Google Analytics * Existing GA4 property * Appropriate permissions to connect third-party applications *** The integration link and detailed steps will be available directly within the Calvin Code interface when setting up your analytics connection. # clarity For comprehensive setup instructions and obtaining access tokens for Microsoft Clarity Data Export API, please refer to the official Microsoft documentation: [**Microsoft Clarity Data Export API Documentation**](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-data-export-api#obtaining-access-tokens) This documentation covers: * Obtaining access tokens * API authentication * Rate limits and usage guidelines * Data export procedures *** For Calvin Code integration assistance, please [contact us](https://www.gopersonal.com/es/contact). # bigquery This comprehensive guide shows you how to create a Google Cloud service account with the necessary permissions for BigQuery MCP integration, using both the Google Cloud Console UI and command-line tools. ## Table of Contents 1. [Prerequisites](#prerequisites) 2. [Method 1: Google Cloud Console (UI)](#method-1-google-cloud-console-ui) 3. [Method 2: Command Line (gcloud CLI)](#method-2-command-line-gcloud-cli) 4. [Required Permissions](#required-permissions) 5. [Converting to Base64](#converting-to-base64) 6. [Troubleshooting](#troubleshooting) ## Prerequisites * A Google Cloud Platform account * An existing GCP project (or create a new one) * Billing enabled on your project * Project Owner or Editor permissions, or specific IAM roles: * `roles/iam.serviceAccountAdmin` * `roles/iam.serviceAccountKeyAdmin` * `roles/resourcemanager.projectIamAdmin` ## Method 1: Google Cloud Console (UI) ### Step 1: Access the Google Cloud Console 1. Go to [Google Cloud Console](https://console.cloud.google.com/) 2. Sign in with your Google account 3. Select your project from the dropdown at the top of the page ### Step 2: Enable Required APIs 1. Navigate to **APIs & Services** → **Library** 2. Search for "BigQuery API" and click on it 3. Click **Enable** if not already enabled 4. Repeat for "Cloud Resource Manager API" if creating a new project ### Step 3: Create a Service Account 1. Navigate to **IAM & Admin** → **Service Accounts** 2. Click **+ CREATE SERVICE ACCOUNT** 3. Fill in the service account details: * **Service account name**: `bigquery-mcp-service` * **Service account ID**: `bigquery-mcp-service` (auto-generated) * **Description**: `Service account for BigQuery MCP access` 4. Click **CREATE AND CONTINUE** ### Step 4: Grant Permissions 1. In the **Grant this service account access to project** section: * Click **Select a role** * Choose one of the following roles based on your needs: * For read-only access: Search for "BigQuery Data Viewer" and select **BigQuery Data Viewer** (`roles/bigquery.dataViewer`) * For query execution: Search for "BigQuery User" and select **BigQuery User** (`roles/bigquery.user`) * For full admin access: Search for "BigQuery Admin" and select **BigQuery Admin** (`roles/bigquery.admin`) 2. Click **CONTINUE** 3. Skip the optional "Grant users access to this service account" section 4. Click **DONE** ### Step 5: Create and Download Service Account Key 1. In the Service Accounts list, find your newly created service account 2. Click on the service account name to open its details 3. Navigate to the **KEYS** tab 4. Click **ADD KEY** → **Create new key** 5. Select **JSON** as the key type 6. Click **CREATE** 7. The JSON key file will automatically download to your computer 8. **Important**: Store this file securely and never share it publicly ### Step 6: Note Your Project ID 1. In the Google Cloud Console header, note your **Project ID** 2. You'll need this for the MCP configuration ## Method 2: Command Line (gcloud CLI) ### Step 1: Install and Setup gcloud CLI 1. Install the Google Cloud CLI from 2. Authenticate with your Google account: ```bash gcloud auth login ``` 3. Set your project (replace `YOUR_PROJECT_ID`): ```bash gcloud config set project YOUR_PROJECT_ID ``` ### Step 2: Enable Required APIs ```bash # Enable BigQuery API gcloud services enable bigquery.googleapis.com # Enable Cloud Resource Manager API (if needed) gcloud services enable cloudresourcemanager.googleapis.com ``` ### Step 3: Create Service Account ```bash gcloud iam service-accounts create bigquery-mcp-service \ --display-name="BigQuery MCP Service Account" \ --description="Service account for BigQuery MCP access" ``` ### Step 4: Grant BigQuery Permissions ```bash # Get your project ID PROJECT_ID=$(gcloud config get-value project) # Choose one of the following based on your needs: # Option 1: Grant BigQuery Data Viewer role (read-only access) gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:bigquery-mcp-service@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/bigquery.dataViewer" # Option 2: Grant BigQuery User role (query execution) gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:bigquery-mcp-service@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/bigquery.user" # Option 3: Grant BigQuery Admin role (full admin access) gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:bigquery-mcp-service@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/bigquery.admin" ``` ### Step 5: Create and Download Service Account Key ```bash # Create and download the service account key gcloud iam service-accounts keys create ./bigquery-service-account.json \ --iam-account=bigquery-mcp-service@$PROJECT_ID.iam.gserviceaccount.com # Verify the file was created ls -la bigquery-service-account.json ``` ## Required Permissions Configure the required roles and permissions to complete this task. You will need the **BigQuery User** role (`roles/bigquery.user`), the **BigQuery Data Viewer** role (`roles/bigquery.dataViewer`), or equivalent IAM permissions to connect to the instance. The service account needs one of the following permission configurations for BigQuery MCP: ### Recommended Roles (Choose One) * **BigQuery User** (`roles/bigquery.user`) - Standard user access to run queries and jobs * **BigQuery Data Viewer** (`roles/bigquery.dataViewer`) - Read-only access to datasets and tables * **BigQuery Admin** (`roles/bigquery.admin`) - Full administrative access to BigQuery resources ### Alternative Granular Permissions (if you prefer minimal permissions) Instead of BigQuery Admin, you can grant these specific permissions: * `bigquery.datasets.create` * `bigquery.datasets.get` * `bigquery.datasets.getIamPolicy` * `bigquery.datasets.update` * `bigquery.jobs.create` * `bigquery.jobs.get` * `bigquery.jobs.list` * `bigquery.tables.create` * `bigquery.tables.delete` * `bigquery.tables.get` * `bigquery.tables.getData` * `bigquery.tables.list` * `bigquery.tables.update` * `bigquery.tables.updateData` ### To grant granular permissions via CLI: ```bash # Create a custom role with minimal permissions gcloud iam roles create bigqueryMcpRole \ --project=$PROJECT_ID \ --title="BigQuery MCP Role" \ --description="Minimal permissions for BigQuery MCP" \ --permissions="bigquery.datasets.create,bigquery.datasets.get,bigquery.datasets.getIamPolicy,bigquery.datasets.update,bigquery.jobs.create,bigquery.jobs.get,bigquery.jobs.list,bigquery.tables.create,bigquery.tables.delete,bigquery.tables.get,bigquery.tables.getData,bigquery.tables.list,bigquery.tables.update,bigquery.tables.updateData" # Assign the custom role gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:bigquery-mcp-service@$PROJECT_ID.iam.gserviceaccount.com" \ --role="projects/$PROJECT_ID/roles/bigqueryMcpRole" ``` ## Converting to Base64 For some configurations, you may need to convert your service account JSON to base64 encoding. ### Method 1: Online Tool 1. Go to 2. Copy the entire contents of your `bigquery-service-account.json` file 3. Paste it into the text area on the website 4. Click **Encode** to get the base64 string 5. Copy the resulting base64 string ### Method 2: Command Line (macOS/Linux) ```bash # Convert JSON file to base64 base64 -i bigquery-service-account.json # Or save to a file base64 -i bigquery-service-account.json > service-account-base64.txt # To decode back (for verification) base64 -d service-account-base64.txt > decoded-service-account.json ``` ### Method 3: Command Line (Windows) ```powershell # PowerShell method [Convert]::ToBase64String([IO.File]::ReadAllBytes("bigquery-service-account.json")) # Or using certutil certutil -encode bigquery-service-account.json service-account-base64.txt ``` ### Method 4: Python (Cross-platform) ```python import base64 import json # Read and encode the JSON file with open('bigquery-service-account.json', 'rb') as f: encoded = base64.b64encode(f.read()).decode('utf-8') print(encoded) ``` ## Next Steps: Configure MCP Once you have your service account JSON file (and optionally base64 encoded), you can configure the BigQuery MCP: 1. Download the GenAI toolbox: ```bash curl -O https://storage.googleapis.com/genai-toolbox/v0.13.0/darwin/arm64/toolbox chmod +x toolbox ``` 2. Add the MCP configuration: ```bash claude mcp add-json bigquery-toolbox '{ "command": "./toolbox", "args": ["--prebuilt", "bigquery", "--stdio"], "env": { "BIGQUERY_PROJECT": "YOUR_PROJECT_ID", "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/bigquery-service-account.json" } }' ``` ## Troubleshooting ### Common Issues **Error: "Permission denied"** * Ensure your user account has the necessary IAM permissions * Verify the service account has the correct roles assigned * Check that the required APIs are enabled **Error: "Service account not found"** * Verify the service account was created successfully * Check that you're using the correct project ID * Ensure the service account email format is correct **Error: "Invalid key file"** * Verify the JSON file is valid and not corrupted * Check file permissions and ensure it's readable * Make sure the file path in the configuration is correct **Error: "Quota exceeded"** * Check your project's API quotas * Ensure billing is enabled on your project * Verify you haven't exceeded service account limits ### Verification Commands ```bash # List service accounts gcloud iam service-accounts list # Check service account permissions gcloud projects get-iam-policy $PROJECT_ID \ --flatten="bindings[].members" \ --format="table(bindings.role)" \ --filter="bindings.members:bigquery-mcp-service@$PROJECT_ID.iam.gserviceaccount.com" # Test BigQuery access bq --project_id=$PROJECT_ID ls # Validate JSON file cat bigquery-service-account.json | python -m json.tool ``` ## Security Best Practices 1. **Store credentials securely**: Never commit service account keys to version control 2. **Use least privilege**: Grant only the minimum permissions needed 3. **Rotate keys regularly**: Create new keys and delete old ones periodically 4. **Monitor usage**: Enable audit logging to track service account usage 5. **Use short-lived tokens when possible**: Consider using Workload Identity Federation for enhanced security ## Support If you encounter issues: 1. Check the [Google Cloud Status page](https://status.cloud.google.com/) 2. Review the [BigQuery documentation](https://cloud.google.com/bigquery/docs) 3. Visit the [Google Cloud Console support page](https://console.cloud.google.com/support) 4. Check the Claude MCP documentation for configuration issues # Tips & Memory How Calvin learns from your team and gets smarter over time Calvin has two complementary learning systems: Tips (manual, curated knowledge) and Memory (automatic learning from completed tasks). Together, they ensure that Calvin gets better at understanding your team's preferences, standards, and workflows with every interaction. Tips are curated knowledge entries that you create to guide how agents behave. Think of them as a knowledge dataset — explicit instructions that teach Calvin your coding conventions, design preferences, workflow patterns, or business rules. The Tips page in the sidebar lets you manage all tips across your store. To create a tip, click "Create Your First Tip" on the Tips page or use the "+" button in the chat input and select "Tip." The creation form has three sections. The Tip Description explains what the tip helps accomplish — for example, "How to optimize product images for better performance." You can click "Generate Examples" to have Calvin suggest content based on your description. The Tip Content is the actual instruction (up to 150 characters) that should be specific and actionable. The Settings section lets you configure the tip's visibility and targeting, including its Status (Published or Draft), which Workspace it applies to (a specific workspace or All Workspaces), and which Workspace Type it targets (a specific type like Web Development or All Types). Tips can be targeted broadly or narrowly. A tip set to All Workspaces and All Types will apply everywhere. A tip targeted to a specific workspace or workspace type will only influence agents working in that context. This lets you maintain general standards across your organization while also having workspace-specific or technology-specific guidance. The Tips page has several additional features. The Filters button lets you filter tips by various criteria. The Internal Tips button shows tips that Calvin has generated internally based on its interactions. The Enhance button helps you improve existing tips by refining their content. Calvin also requests tips proactively during chat sessions. When an agent encounters a situation where guidance would be helpful, it may ask you for input that could become a new tip. Draft tips suggested by Calvin appear on the Home dashboard under "Draft Tips," where you can review, edit, and publish them. Memory is Calvin's automatic learning system that works in the background. When you complete a chat, Calvin analyzes the entire session — the task you described, the approach the agent took, the adjustments you requested, and the final outcome. From this analysis, Calvin extracts learnings and proposes them as memories for your confirmation. You decide which memories to keep. Confirmed memories are stored and applied automatically to future tasks, so Calvin does not repeat the same mistakes or need the same corrections twice. Over time, this creates a compounding effect where Calvin becomes increasingly aligned with how your team works. The distinction between tips and memory is important. Tips are proactive — you create them to establish standards before work begins. Memory is reactive — it captures lessons learned from actual work after it happens. Together, they form a complete learning loop: tips set expectations, work happens, memory captures refinements, and the cycle continues. # Artifacts Share and reuse outputs across your team Artifacts are outputs generated within workspaces that can be shared and reused across your team. They might include code components, analytical reports, design assets, configuration files, or any other deliverable that Calvin produces during a chat session. The Artifacts page in the sidebar provides a centralized view of all artifacts across your store. You can search artifacts by name and filter them by visibility: All shows everything you have access to, Public shows artifacts visible to all team members, Private shows artifacts only you can see, and Shared With Me shows artifacts that other team members have specifically shared with you. The page supports both grid and list views for browsing. Artifacts are created when they are shared from a workspace. During or after a chat session, outputs can be published as artifacts so they are accessible outside the workspace context. This is useful when one team member creates a component or report that others need to reference or build upon. You can also reference artifacts directly within chats. The "+" menu in the chat input includes an Artifacts option that lets you attach an existing artifact to your current conversation. This allows Calvin's agents to use previously created outputs as context when working on a new task — for example, referencing a design system artifact when building new UI components, or pulling in a data analysis artifact when creating a follow-up report. # Task Manager & Sprints Organize your work into sprints and track progress The Task Manager provides a sprint-based project management layer on top of Calvin's workspaces. It helps you organize tasks into sprints, track their status, and get visibility into how work is progressing across your team. The Task Manager page is accessible from the sidebar and shows your sprints in a two-panel layout. The left panel lists all sprints with search and status filtering. The right panel shows the tasks within the selected sprint, including a summary of completed, working, and total tasks along with a completion rate percentage. Each sprint acts as a container for related tasks. You can create sprints using the "+" button in the sprint panel and organize your work according to your team's cadence — whether that is weekly sprints, feature-based batches, or any other grouping that makes sense for your workflow. Tasks within a sprint are displayed in a table with columns for the task name, its associated workspace or identifier, the assigned owner, and the current status. You can search through tasks using the search bar and filter by status using the dropdown. The "Add Task" button lets you create new tasks directly within a sprint. Task statuses align with Calvin's chat lifecycle. A task with a Working status means the corresponding chat is still active. When the chat is completed, the task status updates accordingly. This gives you a high-level view of operational progress without needing to open each workspace individually. The Task Manager is particularly useful for teams managing multiple workspaces and chats simultaneously. It provides the project management visibility that operations leaders need to understand throughput, identify bottlenecks, and plan future work. # Version Control & Git Branching, versioning, and connecting to your repositories Calvin has built-in version control that integrates with your existing Git workflows. Every workspace maintains a complete version history, and every chat operates on its own feature branch to keep changes isolated until you are ready to merge. The version selector in the workspace toolbar displays a list of all saved versions (v1, v2, v3, and so on) with timestamps showing when each was created. You can click on any version to view or restore the workspace to that point in time. This gives you a safety net — if a chat goes in the wrong direction, you can always roll back. Each chat automatically creates a feature branch. When you create a new chat, Calvin branches off from the target branch, and all work the agent does happens on that feature branch. This means multiple chats can run in parallel within the same workspace without conflicting. The current branch name is displayed at the bottom of the workspace (for example, "feature/test"). When creating a new chat, you can specify a custom branch name under Advanced Options if you want to follow your team's naming conventions. Calvin supports four source code management options, configured through the workspace settings. Internal Git is the default, where Calvin creates and manages a private Git repository for you. This is the simplest option and requires no external setup. Use GitHub lets you connect to your own GitHub repository, so Calvin pushes code directly to your GitHub account. Use Bitbucket connects to your Bitbucket repository. Use GitLab connects to your GitLab repository. When using an external repository (GitHub, Bitbucket, or GitLab), Calvin syncs code bidirectionally. The agent works on feature branches within Calvin's environment, and when a chat is completed, changes are pushed to your external repository according to the configured chat closing action. The target branch setting determines which branch feature branches merge into. The default is "main," but you can set it to "develop," "staging," or any other branch that fits your workflow. This is configured in the workspace settings panel. The chat closing action defines what happens to code when a chat is completed. "Merge and Push" automatically merges the feature branch into the target branch when the chat is completed. This is ideal for teams that trust Calvin's output and want fast iteration. "Create Pull Request" creates a pull request to the target branch instead of merging directly. This is ideal for teams that want a human review step before code reaches the target branch, and it integrates naturally with your existing CI/CD pipeline. The Git controls in the file explorer toolbar provide additional options. View Tree shows the complete file tree at the current state. Tools provides Git-related utilities. Take over gives you manual control of the Git state when needed. # Deploying Ship to production on Calvin or deploy to your own infrastructure Calvin provides two paths to production: deploy directly to Calvin's managed infrastructure for instant deployment, or connect your repository to your own CI/CD pipeline and deploy wherever you choose. To deploy on Calvin, click the Deploy button in the workspace toolbar. A panel opens with the message "Ready to Deploy?" and offers to configure your project for instant deployment. Calvin optimizes your build and configures everything automatically, setting your application to run on port 8080. Click "Configure Project" to proceed, and Calvin handles the rest — building, optimizing, and deploying your application to Calvin's hosting infrastructure. Deployed applications consume Runtime credits (as opposed to Builder credits, which are consumed during agent execution). Runtime costs cover the compute, database, storage, and other resources that keep your application running. You can monitor these costs in the Usage Analytics section. Once deployed, the three-dot menu in the workspace toolbar provides access to runtime monitoring features. Open App launches your deployed application in a new tab. Traffic shows real-time traffic data for your application. Web Analytics provides visitor analytics and engagement metrics. Web Performance displays performance metrics to help you identify and resolve bottlenecks. For teams that prefer to deploy to their own infrastructure, Calvin integrates seamlessly with external Git providers. By connecting your workspace to a GitHub, Bitbucket, or GitLab repository (configured in workspace settings), all code changes are pushed to your repository. From there, your existing CI/CD pipeline can pick up the changes and deploy them wherever you need — AWS, Google Cloud, Vercel, Netlify, or any other hosting provider. When using the external deployment approach, configure your chat closing action to either "Merge and Push" (for automatic merges that trigger your CI/CD pipeline) or "Create Pull Request" (for a review step before deployment). This keeps Calvin's output flowing into your existing deployment workflow without requiring any changes to your infrastructure. # Usage Analytics & Billing Track costs, monitor usage, and manage your billing The Usage Analytics page gives you full visibility into how your team is using Calvin and what it costs. It is accessible from the sidebar and provides three views: Overview, Builder, and Runtime. Calvin's pricing model is based on operational minutes. You purchase packs of minutes, and Calvin converts them into resolved technical work. There are two types of credits that correspond to the two phases of Calvin's operation. Builder credits are consumed when agents are actively working on tasks. This is the AI execution time — the minutes an agent spends analyzing your request, writing code, creating files, running commands, and delivering results. Builder cost is calculated based on minutes used at a per-minute rate (for example, $1.5 per minute). The Usage Analytics Overview shows your total builder minutes consumed and the associated cost. Runtime credits are consumed by deployed applications and their infrastructure. When you deploy an application on Calvin, the compute resources, databases, storage, and other services it uses generate runtime costs. Runtime pricing is separate from builder pricing and reflects the actual infrastructure consumed. The Overview tab displays three key metrics for the selected period: Builder Cost (total minutes used and cost), Runtime Cost (infrastructure costs broken down by resource type), and Total Cost (the combined figure). Below these metrics, a Cost Distribution by Workspace chart shows a horizontal bar graph breaking down builder and runtime costs for each workspace, making it easy to see which workspaces are consuming the most resources. The date range selector in the top right lets you choose the period to analyze. This is useful for tracking month-over-month trends, reviewing costs for specific projects, or reconciling billing. The Builder tab provides deeper detail on agent execution time, while the Runtime tab breaks down infrastructure costs by resource type (compute, database, and other services). Billing accounts are managed from Settings under Store Settings. You can select an existing billing account or create a new one. The billing account is linked to your store and determines how usage charges are invoiced. # Settings & Administration Manage your store, team members, and billing The Settings page is where you manage your store configuration, team membership, and billing. It is accessible from the sidebar and has two main tabs: Members and Store Settings. The Members tab shows all team members in your store with their name, email, and role. The available roles are Owner (full administrative access including billing, settings, and member management) and Member (access to workspaces, agents, and operational features). To invite a new team member, enter their email address, select their role from the dropdown, and click "Send Invite." The invitation is sent via email, and the new member will have access to the store once they accept. You can also invite team members directly from the Home dashboard using the "Invite Your Team" section, which provides the same email and role selection interface. The Store Settings tab has two sub-sections: General and Danger Zone. Under General, you can rename your store by entering a new name and clicking "Rename Store." The store name appears in the top-right corner of the application and is used to identify your organization across Calvin. Also under General is the Billing Account section, where you can select an existing billing account or create a new one. The billing account determines how your usage is invoiced and can be updated at any time using the "Update Billing Account" button. The Danger Zone contains destructive actions that cannot be easily undone. These should be used with caution and are typically reserved for situations where you need to make significant changes to your store configuration. # Audit Logs Track all activities and changes across your store The Audit Logs page provides a complete record of all activities and changes that happen within your store. This is essential for enterprise teams that need accountability, compliance tracking, and the ability to review what happened and when. The audit log is displayed as a table with columns for Timestamp (when the event occurred), Event (what type of action was taken), Workspace (which workspace was affected), Details (additional context about the event), User ID (who performed the action), and Actions (options for further investigation). Three filters are available at the top of the page to narrow down the results. The date range selector lets you define a specific time period to review — by default it shows the last seven days. The workspace filter lets you focus on events from a specific workspace or view all workspaces at once. The event type filter lets you narrow results to specific categories of events. Audit logs are particularly valuable for teams operating in regulated environments or those that need to maintain a clear record of who changed what and when. They provide the transparency needed to troubleshoot issues, review agent behavior, and ensure that all operations are properly tracked. # Events All actions tracked in the audit log, grouped by area. *** ## Store | Event | Description | | ------------- | ------------------------------- | | Store Created | A new store was created | | Store Updated | Store configuration was changed | | Store Deleted | A store was removed | ## Team | Event | Description | | ------------------- | -------------------------------- | | Member Invited | A new team member was invited | | Member Removed | A team member was removed | | Member Role Changed | A team member's role was updated | ## Workspace | Event | Description | | --------------------------- | --------------------------------------------- | | Workspace Created | A new workspace was created | | Workspace Updated | Workspace settings were modified | | Workspace Deleted | A workspace was removed | | Workspace MCPs Updated | Workspace MCP server connections were changed | | Workspace Knowledge Updated | Workspace knowledge sources were modified | | Workspace Agents Updated | Workspace agent assignments were changed | ## Chat | Event | Description | | -------------------- | -------------------------------------------------- | | Chat Created | A new chat was started | | Chat Status Changed | A chat's status was updated | | Chat Mode Changed | A chat's operating mode was switched | | Chat Transferred | A chat was moved to a different workspace or agent | | Chat Deleted | A chat was removed | | Chat Cleared | A chat's messages were cleared | | Chat Closed | A chat was closed | | Chat Cancelled | A chat was cancelled | | Chat Completed | A chat was marked as complete | | Chat Sprint Assigned | A chat was assigned to a sprint | | Chat Branch Deleted | A chat's associated code branch was deleted | ## Sprint | Event | Description | | -------------- | ---------------------------- | | Sprint Created | A new sprint was created | | Sprint Updated | Sprint details were modified | | Sprint Deleted | A sprint was removed | ## Agent | Event | Description | | ------------------ | ----------------------------------------- | | Agent Created | A new agent was configured | | Agent Updated | Agent settings were modified | | Agent Deleted | An agent was removed | | Agent MCPs Updated | Agent MCP server connections were changed | ## Knowledge | Event | Description | | ----------------- | -------------------------------- | | Knowledge Created | A new knowledge source was added | | Knowledge Updated | A knowledge source was modified | | Knowledge Deleted | A knowledge source was removed | ## Artifact | Event | Description | | ---------------------- | ---------------------------------------------- | | Artifact Created | A new artifact was generated | | Artifact Shared | An artifact was shared externally | | Artifact Share Revoked | An artifact's external share link was disabled | ## Version Control | Event | Description | | ----------------- | ------------------------------- | | Version Committed | Code changes were committed | | Version Changed | The active version was switched | | Branch Changed | The active branch was switched | ## Billing | Event | Description | | ---------------------------- | ------------------------------------------- | | Billing Account Created | A new billing account was set up | | Billing Account Tier Changed | The billing plan was upgraded or downgraded | ## Infrastructure | Event | Description | | ---------------------- | ----------------------------------- | | Database Provisioned | A new database was created | | Database Deprovisioned | A database was removed | | File Uploaded | A file was uploaded | | Build Restarted | The application build was restarted | # Use Cases & Recipes Practical examples of what you can accomplish with Calvin Calvin is designed to handle the operational tasks that slow eCommerce teams down. Here are practical scenarios that demonstrate how different teams use Calvin to turn hours of work into minutes of execution. Building landing pages and UI components is one of the most common use cases. A brand needed new screens while their designer was on leave. Using Calvin with a Web Development workspace, they described the layouts they needed in natural language and attached their brand guidelines. Calvin's Full Stack Developer agent generated complete, brand-compliant components and layouts in under three minutes — work that would normally take 20 to 40 hours of back-and-forth between design and development. Generating analytics reports and visualizations is another area where Calvin delivers immediate value. Teams that spend hours manually building reports in GA4 or other analytics platforms can describe the insights they need, and Calvin's Analyst agent generates the visualizations and delivers actionable insights. One team reduced their reporting time from 8 to 12 hours down to about 3 minutes of agent execution, with an additional 4 minutes of fine-tuning adjustments. Product catalog management benefits greatly from Calvin's automation capabilities. An eCommerce team that struggled to produce descriptions for their entire catalog used Calvin to create a product description optimizer. The agent built a tool that generates, corrects, and publishes product descriptions automatically. The initial tool was created in under 6 minutes, and individual descriptions are produced in under 35 seconds each. Running QA and validation before releases helps teams catch issues early. Using a Web QA workspace, you can describe what needs to be tested, and the Web QA Specialist agent systematically checks for errors, validates functionality, and reports issues — all before anything goes live. This reduces the QA bottleneck that often delays releases. Building automation workflows with n8n is streamlined through Calvin's n8n Workflow Developer agent. Rather than manually configuring n8n nodes and connections, you describe the workflow you need ("When a new order comes in, check inventory, send a confirmation email, and update the CRM"), and the agent builds it. Creating custom internal tools is another powerful use case. When your team needs a backoffice tool, an admin dashboard, or a data processing utility, Calvin can build it from scratch in a fraction of the time it would take a developer. Describe the functionality you need, and the agent scaffolds the entire application — frontend, backend, and database — ready for deployment. For agencies managing multiple brands, Calvin scales horizontally. Each brand can have its own workspace with its own configuration, tips, and memory. Agents learn the specific conventions of each brand independently, so switching between clients does not mean starting from zero each time. # Modes Calvin supports different modes that let you control how the agent approaches your tasks. Each mode is optimized for a specific type of interaction, from planning and exploration to rapid fixes and long-running complex tasks. ### Plan Mode Plan Mode is designed for collaborating with the agent to build a structured plan before any code is written. The agent will analyze your request, ask clarifying questions, and produce a detailed execution plan. Once the plan is ready, you can request adjustments or approve it and move on. From Plan Mode, you can either ask for changes to the plan or transition to Build Mode to start implementing it. Importantly, when switching from Plan Mode to Build Mode, the plan is automatically carried over so the agent maintains full context. ### Build Mode Build Mode is the standard development mode where the agent actively writes, modifies, and iterates on your codebase. You can start a chat directly in Build Mode without going through Plan Mode first — it is the default mode for most development tasks. When switching between Build Mode and Flash Mode, we recommend starting a new chat or clicking "Clear Chat" to ensure the agent is working with a clean context and performs at its best. ### Ask Mode Ask Mode is a read-only mode intended for questions and exploration. The agent will answer your questions and provide guidance without making any changes to your codebase. Use this mode when you want to understand how something works, get explanations, or explore options — without triggering any modifications. If you switch from Ask Mode to Build Mode or Flash Mode, the agent session is reset and the agent will only see your latest message. ### Flash Mode Flash Mode is a fast, lightweight mode built for small changes and quick fixes. It is generally faster than Build Mode, but it is only recommended for well-defined or small-scope tasks. For larger or more complex requirements, Build Mode will deliver better results. When switching modes mid-chat (for example, from Ask to Flash or from Ask to Build), the agent session resets and the agent will only have visibility into the user's latest message — it does not retain previous conversation history. For the best results with Flash Mode, we recommend starting a fresh chat or clicking "Clear Chat" before using it. ### Epic Mode Epic Mode is designed for long-running, complex tasks that require thorough execution and validation. In this mode, multiple specialized agents — both development and validation agents — collaborate on the task. The agent iterates 3 times on the task to ensure that the original requirements are fully met before delivering a result. Use Epic Mode when the scope is large, the requirements are nuanced, or when quality assurance is critical. It takes more time than other modes, but offers the highest level of completeness and reliability for demanding tasks. ### How to Use Modes #### Starting a Chat in a Specific Mode You can select the mode before starting a new chat. The mode selector is available in the chat interface, allowing you to choose the right mode for your task from the very beginning.
#### Changing the Mode in an Existing Chat You can also change the mode from within an active chat. Here is how each mode transition behaves: When switching from Plan Mode to Build Mode, the plan is automatically passed along so the agent retains the full context and can immediately start building. When switching from Ask Mode to Build Mode or Flash Mode, the agent session is reset. The agent will only see the user's latest message and will not have access to previous conversation history. When switching between Build Mode and Flash Mode, the session also resets. For best results, we recommend starting a new chat or clicking "Clear Chat" before using Flash Mode, so the agent can focus on the task without unnecessary context overhead.
# Calvin AI Models ## Overview Calvin is built on a multi-model, multi-agent architecture, combining several types of AI technologies to deliver intelligent, context-aware e-commerce experiences. Rather than relying on a single model, Calvin orchestrates a diverse set of AI components — including LLMs, embedding models, reranking models, vector databases, and graph databases — each selected for the specific task it performs best. Within each workspace, multiple specialized agents collaborate using different models: some build, some review, and some research, working together much like a real development team. ## Model Categories ### Large Language Models (LLMs) Calvin employs multiple LLMs across its platform, organized around a workspace-based architecture. Each workspace contains a team of specialized agents, and each agent is paired with the LLM best suited for its role. Some agents are dedicated builders, responsible for generating UI components, writing production-ready code, and implementing platform integrations. Others serve as reviewers, running QA checks, validating outputs against best practices, and ensuring code quality before anything reaches production. Additional agents focus on research and analysis — synthesizing user behavior data, extracting insights from product catalogs, or evaluating A/B test results. This division of labor mirrors how a real development team operates, with different specialists collaborating within the same workspace to deliver high-quality results. This multi-model approach means Calvin is not locked into a single provider or architecture. Calvin combines in-house models developed specifically for e-commerce workflows with leading proprietary models from top AI providers. In-house models handle tasks where domain-specific optimization and data control are critical, while proprietary models are used where general-purpose reasoning and generation capabilities are needed. Each agent's model assignment is continuously evaluated and updated to ensure the best balance of performance, accuracy, and cost efficiency. Because different agents serve different purposes, they often run on entirely different models. A developer agent tasked with generating complex React components might use a large, highly capable reasoning model, while a reviewer agent performing code linting might use a faster, more cost-efficient model optimized for pattern detection. Meanwhile, a research agent scanning competitor pricing strategies could leverage a model fine-tuned for data extraction and summarization. This flexibility allows each workspace to maintain an optimal balance of speed, intelligence, and cost — tailored to the exact mix of tasks at hand. ### Embedding Models Calvin uses embedding models to transform product catalogs, user queries, and behavioral signals into rich vector representations. These embeddings power semantic search, product discovery, and recommendation systems — enabling Calvin to understand intent rather than just match keywords. ### Reranking Models After initial retrieval, reranking models refine and reorder results based on deeper contextual understanding. This ensures that the most relevant products, content, or actions surface first, improving conversion and user satisfaction. ### Vector Databases Calvin stores and queries vector embeddings through high-performance vector databases, enabling real-time similarity search and retrieval at scale. This infrastructure supports fast, accurate results even across large and complex product catalogs. ### Graph Databases for Memory Management In addition to vector databases, Calvin leverages graph databases to manage long-term memory and contextual relationships across workspaces. Graph databases store structured knowledge as interconnected nodes and edges, allowing Calvin's agents to maintain rich, persistent memory of past interactions, project history, user preferences, and domain-specific relationships. This graph-based memory layer enables agents to recall prior decisions, understand how different components relate to each other, and carry context across sessions — making each workspace smarter over time. By combining vector search for semantic retrieval with graph structures for relational reasoning, Calvin achieves a deeper level of contextual intelligence that goes beyond simple pattern matching. ## Security and Data Privacy All AI models used by Calvin operate within a secure, isolated network inside AWS. Specifically: * All model inference runs within the same Virtual Private Cloud (VPC), ensuring that data never leaves the secure network boundary. * No customer data is sent to external model providers for training purposes. * Data sovereignty is maintained at every layer — from inference to storage. This architecture is designed to meet enterprise-grade security requirements while still leveraging the latest advances in AI. ## E-Commerce Native Intelligence Calvin's models are not general-purpose AI adapted for e-commerce — they are built from the ground up with deep e-commerce domain knowledge. This means every model in the stack understands the language, patterns, and nuances of online retail: from product taxonomies and catalog structures to conversion optimization and merchandising strategies. Beyond domain knowledge, Calvin's models are equipped with the right tools, up-to-date documentation, and context needed to not just analyze but actually build. Agents understand how to construct UI components, implement platform integrations, generate production-ready code, and work within real e-commerce frameworks. This is achieved through extensive fine-tuning, curated knowledge bases, and purpose-built toolchains that keep models aligned with current best practices, platform APIs, and design patterns. The result is an AI that doesn't just suggest — it executes with the precision of a team that has shipped hundreds of e-commerce projects. ## Why a Multi-Model Approach? No single AI model excels at every task. By combining specialized models across different domains — language understanding, semantic search, ranking, and generation — Calvin achieves a level of performance and flexibility that a monolithic approach simply cannot match. This also allows Calvin to evolve rapidly, adopting new models and techniques as the field advances without disrupting existing workflows. Combined with per-workspace agent teams — where developers, reviewers, and analysts each operate on the model best suited to their task — Calvin delivers a truly collaborative AI experience that scales with your business. # Calvin vs n8n {% stepper %} {% step %} ### Calvin vs n8n Son herramientas de categorías distintas. Pero es una comparación frecuente — así que vale la pena aclararla. {% endstep %} {% step %} ### Dos herramientas, dos propósitos n8n automatiza conexiones entre sistemas. Calvin crea, opera y escala tu ecommerce. | n8n | Calvin | | ------------ | -------------------------------------------------------------------------------- | | Propósito | Automatizar workflows. Conectar sistema A con sistema B. | | Enfoque | Conectar herramientas existentes. Mover datos entre APIs. | | Inteligencia | Reglas y triggers definidos por vos. Si pasa X, hacé Y. Sin razonamiento propio. | | Ecommerce | Genérico. Podés usarlo para ecommerce, pero no sabe de ecommerce. | | Output | Datos movidos, notificaciones enviadas, registros actualizados. | | Usuarios | Técnicos que definen workflows. Requiere entender APIs y lógica. | n8n conecta tus herramientas. Calvin es la herramienta → {% endstep %} {% step %} ### Automatizar ≠ Operar n8n conecta software y automatiza tareas repetitivas. Calvin piensa, diseña, escribe código y aprende tu marca. #### n8n: automatización ⚡ Sincronizar stock entre Shopify y tu ERP\ ⚡ Enviar un email cuando llega una orden nueva\ ⚡ Actualizar precios desde una planilla de Google\ ⚡ Mover datos de un CRM a tu plataforma\ ⚡ Notificar a Slack cuando baja el inventory\ ⚡ Publicar en redes cuando se crea un producto Requiere configuración manual. Necesitás un técnico o una agencia para armarlo. #### Calvin: tu equipo virtual 🧠 Investigar por qué bajó la conversión y proponer cambios\ 🧠 Diseñar y desarrollar una landing de campaña completa\ 🧠 Crear un feature nuevo, testearlo y deployarlo\ 🧠 Analizar el comportamiento de usuarios y optimizar UX\ 🧠 Gestionar la infraestructura y monitorear performance\ 🧠 Coordinar múltiples agentes en un flujo end-to-end Le decís a Calvin lo que querés y él lo construye, lo testea y lo pone a correr. Es como comparar un martillo con un equipo de construcción: el equipo también clava clavos, pero además diseña la casa, la construye, la verifica y la entrega. {% endstep %} {% step %} ### n8n cubre una capa. Calvin cubre todo. La automatización es una de muchas capacidades. Calvin incluye automatización + todo lo demás. | Capa | Calvin | n8n | | ---------------- | --------------------------------------: | ------------------- | | Research & Data | ✓ UX Research Agent, Data Science Agent | ✕ No | | Diseño & UX | ✓ UI Designer Agent | ✕ No | | Desarrollo & QA | ✓ Dev Agent + QA Agent (per platform) | ✕ No | | Automatización | ✓ Custom Agents + Integrations | ✓ Sí (1 de 6 capas) | | Infra & Deploy | ✓ Infra Agent / Building Blocks | ✕ No | | Growth & Revenue | ✓ Growth Agent, Analytics | ✕ No | n8n cubre \~17% de las capacidades. Calvin cubre el 100% — incluyendo la automatización. {% endstep %} {% step %} ### ¿Y si usás los dos? Calvin y n8n se complementan naturalmente. Lo importante: Calvin out of the box te da el ecommerce funcionando, aprende de tu negocio, tiene modelos específicos de ecommerce, y puede generar workflows de n8n como un agente más. #### Calvin genera, n8n ejecuta Calvin crea workflows de n8n con inteligencia — entiende tu negocio, elige los nodos correctos, y lo configura todo. Describís lo que necesitás en lenguaje natural y Calvin lo arma, lo testea y lo despliega. #### Calvin para lo complejo, n8n para lo repetitivo Usá Calvin para procesos que requieren razonamiento: research, diseño, desarrollo, QA, deploy. Usá n8n para la automatización operativa: sync de datos, notificaciones, triggers simples. #### Calvin como orquestador, n8n como integrador Calvin coordina agentes inteligentes y gestiona la operación completa del ecommerce. n8n conecta los sistemas de backoffice y ejecuta las integraciones técnicas. No es Calvin o n8n. Es Calvin como plataforma + n8n como motor de automatización. {% endstep %} {% step %} ### Calvin puede crear workflows de n8n Calvin puede crear workflows de n8n como un agente más. No necesitás una agencia que te cobre miles por armar nodos. {% endstep %} {% step %} {% embed url="" %} {% endstep %} {% step %} ### La diferencia es de categoría, no de funcionalidad. Calvin no es una herramienta de automatización. Es tu equipo operativo de ecommerce. 🔧 n8n automatiza conexiones entre sistemas → Calvin opera tu ecommerce completo ⚡ n8n requiere configuración manual → Calvin lo construye, testea y despliega solo 🏪 n8n no sabe nada de ecommerce → Calvin tiene modelos nativos por plataforma 🧠 n8n ejecuta reglas → Calvin razona, decide y actúa ¿Seguís automatizando partes cuando podrías operar todo? {% endstep %} {% endstepper %} # Calvin vs Chatbots {% stepper %} {% step %} ### Calvin vs ChatGPT, Gemini, Claude.ai "Ya tengo Gemini... ¿para qué necesito Calvin?" {% endstep %} {% step %} ### Sí, Calvin tiene un chat Nuestro workspace "From Scratch" se parece a un chat de propósito general. Pero ahí terminan las similitudes. #### ChatGPT / Gemini / Claude.ai * Interfaz\ Chat de texto. Preguntás, te responde. * Output\ Texto, código, imágenes. Copiás y pegás a otra herramienta. * Contexto\ Sesión efímera. Cada conversación empieza de cero. * Aprendizaje\ Individual. Lo que aprendiste se queda en tu chat. * Ejecución\ Te da una respuesta. Vos ejecutás. * Alcance\ Propósito general. Sabe de todo, pero no es experto en nada. #### Calvin — From Scratch * Interfaz\ Chat + studio visual + editor de código. Creás software y lo usás en el momento. * Output\ Artefactos, Diseño en figma, Notebooks, Software funcional, deployable. Se ejecuta dentro de Calvin sin salir. * Contexto\ Persistente y acumulativo. Calvin conoce tu tienda, tu marca, tu historial. Cross usuarios. * Aprendizaje\ Colectivo. Calvin aprende del uso de todos los usuarios. * Ejecución\ Ejecuta por vos. Desde la idea hasta el deploy en producción. * Alcance\ Nativo ecommerce. Entrenado en operación de tiendas digitales. La diferencia más grande no está en el chat. Está en lo que pasa después → {% endstep %} {% step %} ### De idea a revenue ¿Qué pasa cuando querés llevar una idea a producción? Con un chatbot, vos armás el rompecabezas. Con Calvin, el rompecabezas se arma solo. {% stepper %} {% step %} ### Idea Tengo una idea para mejorar mi tienda. {% endstep %} {% step %} ### Research Validar con datos y comportamiento. {% endstep %} {% step %} ### Diseño Crear la experiencia visual y UX. {% endstep %} {% step %} ### Desarrollo Escribir el código production-ready. {% endstep %} {% step %} ### QA Testear cross-browser y regresión. {% endstep %} {% step %} ### Deploy Subir a producción y monitorear. {% endstep %} {% step %} ### Revenue Medir impacto y optimizar. {% endstep %} {% endstepper %} #### Con un chatbot * ❌ Preguntás en un chat, copiás la respuesta * ❌ Pegás el código en tu editor, lo adaptás * ❌ Buscás otro prompt para el diseño * ❌ Testeás vos manualmente * ❌ Deployás vos con tus herramientas * ❌ Medís impacto... si te acordás #### Con Calvin * ✅ Describís la idea en Calvin * ✅ Los agentes investigan, diseñan, desarrollan * ✅ El código va directo a un feature branch * ✅ QA Agent testea automáticamente * ✅ Deploy a producción desde Calvin * ✅ Data Science Agent mide impacto en real time {% endstep %} {% step %} ### Cuando toda la empresa usa chatbots Funciona para uno. Se rompe para un equipo. #### El problema con chatbots en equipos — Cómo lo resuelve Calvin * ✕ Conversaciones dispersas\ Cada persona tiene sus propios chats. Nadie sabe qué prompt usó el otro, qué se decidió, o qué se descartó.\ ✓ Plataforma centralizada — Todo el trabajo vive en un solo lugar. Cualquier persona del equipo puede ver, continuar, o auditar el trabajo de otro. * ✕ Sin aprendizaje colectivo\ Lo que un usuario descubre no beneficia a los demás. Cada persona repite los mismos errores.\ ✓ Calvin aprende de todos — Cada interacción mejora la plataforma para todos los usuarios. El conocimiento se acumula, no se pierde. * ✕ Cero auditoría\ No sabés quién pidió qué, cuándo, ni qué se generó. Imposible para compliance o governance.\ ✓ Auditoría completa — Registro detallado de cada acción, cada agente, cada decisión. Trazabilidad end-to-end para enterprise. * ✕ Sin control de calidad\ Cada persona valida (o no) lo que el chatbot generó. No hay estándar ni revisión centralizada.\ ✓ QA integrado + governance — Agente de QA, revisiones automáticas, estándares de marca, y flujos de aprobación configurables. * ✕ No escala\ 5 personas usando ChatGPT son 5 silos. 50 personas son 50 silos. Más gente = más caos.\ ✓ Escala con el equipo — Roles, permisos, workflows compartidos. Más personas = más eficiencia, no más caos. {% endstep %} {% step %} ### Calvin no es un chatbot. Es tu equipo operativo de eCommerce. * 💬 Un chatbot te da respuestas → Calvin ejecuta procesos completos * 📋 Un chatbot es una herramienta individual → Calvin es una plataforma de equipo * 🔄 Un chatbot empieza de cero cada vez → Calvin acumula conocimiento y mejora * 🏪 Un chatbot es genérico → Calvin es nativo ecommerce ¿Seguís usando un chatbot para operar tu ecommerce? {% endstep %} {% endstepper %} # Calvin vs Figma Make {% stepper %} {% step %} ### Figma Make vs Calvin Una pregunta frecuente. Comparemos diseñador vs diseñador. Pero esta comparación no es del todo justa: Calvin es una plataforma de empleados virtuales, no solo una herramienta de diseño. | Aspecto | Figma Make | Calvin — Agente de Diseño | | --------------------- | -----------------------------------------------------------------------------------------: | ----------------------------------------------------------------------------------------------- | | Usuarios | Diseñadores, PMs, stakeholders | Diseñadores, PMs, growth, dueños de tienda | | Input | Prompt de texto, imagen o frame de Figma | Prompt de texto, imagen, Figma existente, datos de analytics, insights de research | | Brand / Design System | Extrae estilos (colores) de librería Figma. Componentes y tipografías custom aún limitados | Acceso completo al manual de marca compartido. Aplica componentes, tipografía, y guías de marca | | Research & Datos | No incluye herramientas de research. Dependes de input manual externo | Agente de UX Research integrado: heatmaps, sesiones, entrevistas. Agente de Data Science | | Output | Prototipo interactivo en Figma. HTML "div soup" — no es production-ready | Código production-ready en feature branch. Git-native, listo para review y deploy | | Colaboración | Multiplayer en Figma, edición en tiempo real. Ecosistema cerrado dentro de Figma | Multi-agente: QA, Growth, Data Science colaboran en el mismo branch | | Contexto ecommerce | Genérico — no tiene contexto de ecommerce. No conoce tu catálogo ni métricas | Nativo ecommerce: conoce tu catálogo, conversión, y comportamiento de usuarios | Pero... ¿tiene sentido comparar solo el paso de diseño? Veamos qué pasa realmente en una empresa → {% endstep %} {% step %} ### Pero el diseño no ocurre en el vacío Un diseñador no se despierta un día y decide cambiar el sitio. Hay un proceso completo detrás de cada cambio — disparado por datos, decisiones de negocio, o feedback de usuarios. Tienda Grande — Proceso Real DETONANTES DEL CAMBIO * Científico de Datos: Caída en conversión, aumento de rebote, patrones de búsqueda * Gerente Crecimiento: Tests A/B, análisis de embudo, benchmark competencia * CMO / VP Ecommerce: Iniciativa estratégica, rebranding, nueva campaña * Merchandising Mgr: Lanzamiento colección, reestructura categorías * Líder CX / Soporte: Quejas recurrentes, fricción UX reportada PRIORIZACIÓN → INVESTIGACIÓN → DISEÑO → APROBACIÓN Roles y tareas: * Product Manager: Historia de usuario, define alcance y KPIs, prioriza en backlog * Investigador UX: Mapas de calor, entrevistas usuarios, valida hipótesis * ⭐ Diseñador UX ⭐: Wireframes, flujos de usuario, patrones de interacción * ⭐ Diseñador UI ⭐: Diseño visual, specs componentes, layouts responsivos * Stakeholder / Marca: Aprobación visual y de marca DESARROLLO → QA → LANZAMIENTO → MONITOREO * Dev Frontend: Componentes, responsivo, performance * Dev Backend: APIs, capa de datos, integraciones * QA Engineer: Testing funcional, cross-browser, regresión * Tech Lead: Revisión código, arquitectura, auditoría rendimiento * DevOps + Monitoreo: Deploy staging/prod, feature flags, KPIs e impacto Figma Make solo cubre los 2 pasos resaltados (⭐).\ Calvin cubre el proceso completo: desde el insight de datos hasta el deploy en producción. {% endstep %} {% step %} ### Lo mismo aplica a tiendas pequeñas Menos personas, pero el mismo principio: el cambio no empieza en el diseño. Empieza en un dato, una queja, o una intuición del dueño. Tienda Pequeña — Proceso Real DETONANTES * Dueño revisa analytics: Nota caída en ventas, alto rebote en mobile, abandono de carrito * Persona de Marketing: Campaña necesita landing, competencia se ve mejor, feedback en redes * Intuición del Dueño: Algo no se ve bien, queja de cliente por DM, actualización de temporada DECISIÓN → DISEÑO → APROBACIÓN Roles y flujo: * Dueño / Fundador: Decide prioridad, idea de lo que quiere, define presupuesto y plazo * ⭐ Diseñador ⭐: Mockup en Figma, UX + UI combinados, 1-2 rondas de revisión * Dueño aprueba: Revisión rápida, muestra al socio, OK o pide cambios CONSTRUCCIÓN → REVISIÓN → PRODUCCIÓN * Desarrollador: Frontend + Backend, testea, chequeo cross-device * Dueño revisa: Navega staging, chequea en el celular, marca problemas obvios * Deploy + Monitoreo: Sube a producción, smoke test rápido, mira ventas al otro día Acá tampoco el diseño es un paso aislado. Calvin reemplaza al equipo completo: analiza datos → diseña → desarrolla → testea → despliega. {% endstep %} {% step %} ### ¿Y si usás los dos? No es uno u otro. Figma y Calvin se complementan. Podés importar diseños de Figma a Calvin, trabajar con todos los agentes, y llevar los diseños de vuelta a Figma. Figma * Diseñá en tu herramienta favorita * Usá tus componentes y librerías * Trabajá con tu equipo en Figma * Iterá el diseño visual libremente Importar diseños → Calvin * 🎨 UI Designer Agent: Refina el diseño importado con contexto de marca * 🔍 UX Research Agent: Valida con heatmaps, sesiones, y datos reales * 📈 Growth Agent: Optimiza para conversión y métricas del negocio * 💻 Dev Agent: Genera código production-ready en feature branch * 🧪 QA Agent: Testea cross-browser, responsive, y regresión * 📊 Data Science Agent: Mide impacto y genera insights post-deploy Exportar a Figma → Figma * Recibí los diseños actualizados * Ya validados con datos reales * Con código listo en el branch * Seguí iterando en Figma si querés Lo mejor de los dos mundos: diseñá en Figma, potenciá con Calvin. Sin fricciones, sin vendor lock-in. {% endstep %} {% endstepper %} # Security and Privacy Calvin is built with security and data privacy as core principles. This document outlines how we handle your data, protect your information, and provide you with control over your assets. ## LLM Data Privacy Calvin leverages Large Language Models (LLMs) to power its AI agents. Here's how we ensure your data remains private: * **No training on your data.** Your code, conversations, and business data are never used to train or fine-tune any AI model. This is guaranteed by contract with our LLM providers. * **Private network access.** All LLMs are hosted on AWS and accessed exclusively through private network connections, ensuring your data never traverses the public internet. * **No data persistence.** LLMs do not retain any data from your interactions. Each request is processed in isolation and discarded after the response is generated. ## Data Storage ### Default Storage If no external repository is connected, Calvin stores the minimum data necessary to operate the platform: * Source code generated by agents is hosted on Calvin's infrastructure, encrypted at rest on Amazon S3. * Chat history and workspace data are stored to maintain session continuity. All stored data is encrypted at rest and in transit. ### External Repository Integration Calvin also allows you to connect your own version control provider so that source code is stored exclusively in your own repository and never on Calvin's infrastructure. Supported providers include: * GitHub * Bitbucket * GitLab * Other Git-compatible providers When an external repository is configured, Calvin does not store any copy of your source code on its infrastructure. All code is pushed directly to your repository, and agents interact with it in real time. In this scenario, Calvin only retains chat history and workspace metadata — not the generated code itself. ### BYOS (Bring Your Own Storage) For organizations that require full control over their data, Calvin offers a **Bring Your Own Storage** mode. How it works: {% stepper %} {% step %} ### Provide an S3 bucket You provide your own Amazon S3 bucket. {% endstep %} {% step %} ### Set an encryption password You set an encryption password that only you know. {% endstep %} {% step %} ### Data stored in your bucket All data — chats, messages, code (if using Calvin-hosted repos), and workspace state — is stored exclusively in your bucket, encrypted with your password. {% endstep %} {% step %} ### Temporary decryption for sessions When opening a workspace, you enter your password to temporarily decrypt access to the sandbox connected to your bucket. {% endstep %} {% step %} ### Decrypted access revoked after session Once the session ends, the decrypted access is revoked. {% endstep %} {% endstepper %} Key security properties: * **Zero-knowledge architecture.** Calvin never stores your encryption password. It is used only in memory to encrypt and decrypt access to your S3 bucket during active sessions. Additionally, each workspace runs in an isolated sandbox, and no one — including Calvin — has access to the in-memory state during or after your session. * **Full data ownership.** All data resides in your AWS account, under your control and your access policies. * **Data portability.** Since the data lives in your bucket, you can audit, back up, or migrate it at any time. {% hint style="warning" %} Note: BYOS mode may introduce additional latency compared to default storage, as all read/write operations go through your external bucket. This is the tradeoff for complete storage control. {% endhint %} ## Access Controls Access to Calvin's infrastructure is restricted following the principle of **least privilege**: * Only a limited number of authorized personnel have access to production infrastructure. * Access to customer data occurs only when strictly necessary for technical support or platform maintenance, and never for commercial purposes. * Infrastructure access is managed through differentiated IAM roles on AWS. ## Infrastructure & Compliance Calvin operates entirely on **Amazon Web Services (AWS)**, adhering to AWS security best practices: * **Network isolation** via dedicated VPCs * **Encryption** at rest (AES-256) and in transit (TLS 1.2+) * **Identity and Access Management** with role-based policies * **Infrastructure monitoring** through AWS native services AWS maintains certifications including **SOC 1/2/3**, **ISO 27001**, **ISO 27017**, **ISO 27018**, and **GDPR** compliance. Calvin's infrastructure inherits these guarantees at the infrastructure level. ## Data Retention & Deletion * Calvin retains your data only for as long as your account is active and the data is needed to provide the service. * You can request complete deletion of all your data by contacting our support team. * Upon account termination, all associated data is deleted from Calvin's systems. * In BYOS mode, data retention is entirely under your control since all data resides in your own bucket. ## Intellectual Property All source code, assets, and any other artifacts generated through Calvin are the exclusive intellectual property of the user (or the organization that owns the account). Calvin does not claim any ownership, license, or rights over the output produced by its AI agents. You are free to use, modify, distribute, and commercialize all generated code without any restriction from Calvin. Calvin does not charge royalties, fees, or any percentage of revenue derived from anything you build or generate using the platform. What you create is entirely yours — to own, sell, license, or monetize however you choose, with no claims or involvement from Calvin whatsoever. ## Questions?
Have questions about our security practices or need more details? If you have any questions about our security practices or need more details, contact our team at support.
# Calvin vs v0 vs Lovable {% stepper %} {% step %} ### 1. Calvin vs v0 vs Lovable Son herramientas que prometen construir software con IA. Pero la diferencia es profunda — y se nota cuando el proyecto deja de ser un prototipo. {% endstep %} {% step %} ### 2. Tres herramientas, tres alcances v0 y Lovable construyen frontends y apps simples. Calvin construye, opera y escala soluciones reales. | | v0 (Vercel) | Lovable | Calvin | | --------------- | ------------------------------------ | --------------------------------------- | ------------------------------------------------------- | | Propósito | Generar UIs y apps Next.js | Generar apps full-stack simples | Crear, operar y escalar soluciones completas | | Stack | Next.js, Vercel serverless | React/Vite + Supabase | Cualquiera: Next.js, Python, PHP, Java, Docker custom | | Backend | API routes serverless (max \~13 min) | Supabase Edge Functions (max \~6.5 min) | Cualquier runtime. Procesos de horas, días. Sin límites | | Infraestructura | Vercel (no configurable) | Supabase + hosting propio (limitado) | Infraestructura completa, gestionada, observable | | Output | App deployada en Vercel | App deployada con Supabase | Solución productiva: código, infra, datos, monitoreo | v0 y Lovable generan código. Calvin genera soluciones → {% endstep %} {% step %} ### 3. Generar código ≠ Operar software v0 y Lovable son excelentes para prototipar. Calvin es para construir y operar en producción. #### v0 y Lovable: generadores de código ⚡ Crear una landing page desde un prompt\ ⚡ Generar un dashboard con componentes UI\ ⚡ Scaffoldear un CRUD con autenticación\ ⚡ Prototipar una idea rápidamente\ ⚡ Generar componentes React reutilizables Ideal para validar ideas. Pero cuando necesitás procesos largos, infraestructura real, o inteligencia de dominio — te quedás sin herramientas. #### Calvin: tu equipo de desarrollo completo 🧠 Scrapear un marketplace entero en un proceso de horas\ 🧠 Almacenar datos en PostgreSQL con pgvector, sin configurar nada\ 🧠 Matchear productos con embeddings + reranking de texto e imagen\ 🧠 Redimensionar imágenes con sharp o un paquete Python en tu Docker\ 🧠 Crear dashboards sobre datos reales con triggers automáticos\ 🧠 Observar, debuggear y escalar — todo desde la misma plataforma Le decís a Calvin lo que necesitás y él lo construye, lo despliega y lo opera. {% endstep %} {% step %} ### 4. Caso real: Marketplace Intelligence Necesitás scrapear marketplaces, almacenar productos, y matchear entre sellers usando similaridad de vectores y reranking — con dashboards para operar. #### Scraping de datos en procesos largos | | v0 | Lovable | Calvin | | --------------- | --------------------------- | ------------------------------- | --------------------------------------- | | Procesos largos | ❌ Max \~13 min (Vercel Pro) | ❌ Max \~6.5 min (Supabase Edge) | ✅ Sin límite. Horas, días | | Runtime | Solo Node.js/Edge | Solo Deno/TypeScript | Cualquiera: Python, Node, Java, etc. | | Docker custom | ❌ | ❌ | ✅ Dockerfile con las deps que necesites | Para scrapear un marketplace entero, necesitás procesos que corran horas. v0 y Lovable no pueden. Calvin sí. #### Base de datos y vectores | | v0 | Lovable | Calvin | | ------------- | ------------------------------------------------ | --------------------------------- | ---------------------------------------- | | Base de datos | ❌ Necesitás integrar Vercel Postgres, Neon, etc. | ✅ Supabase Postgres (incluido) | ✅ PostgreSQL como Block, listo para usar | | pgvector | ❌ Requiere setup manual con proveedor externo | ✅ pgvector disponible en Supabase | ✅ pgvector incluido en el Block de DB | | Configuración | Manual, por prompt | Semi-automático | Zero config. El Block viene listo | #### Embeddings | | v0 | Lovable | Calvin | | ------------------ | -------------------------------- | ------------------------------- | ------------------------------------------------- | | Generar embeddings | ❌ Necesitás OpenAI, Cohere, etc. | ❌ Necesitás proveedor externo | ✅ Block de Embeddings. Sin API keys, sin terceros | | Modelos | Depende del proveedor | Depende del proveedor | Modelos incluidos out of the box | | Integración | Manual: SDK + API key + código | Manual: Edge Function + API key | Automática. Plug & play | #### Reranking | | v0 | Lovable | Calvin | | ------------------- | -------------- | -------------- | ---------------------------- | | Reranking de texto | ❌ No soportado | ❌ No soportado | ✅ Block de Reranker incluido | | Reranking de imagen | ❌ No soportado | ❌ No soportado | ✅ Soportado como Block | | Setup | N/A | N/A | Zero config | #### Procesamiento de imágenes | | v0 | Lovable | Calvin | | ------------------------------ | -------------------------------------- | --------------------------------------------- | ------------------------------------------- | | sharp (Node.js) | ⚠️ Posible pero limitado en serverless | ❌ Edge Functions no soportan binarios nativos | ✅ Agregás sharp al Docker y listo | | Paquetes Python (Pillow, etc.) | ❌ No soporta Python | ❌ No soporta Python | ✅ Python en Docker con las deps que quieras | | Custom Dockerfile | ❌ | ❌ | ✅ | #### Triggers y scheduling | | v0 | Lovable | Calvin | | ----------------- | ------------------ | ---------------------- | ------------------------------------------ | | Cron / scheduling | ✅ vercel.json cron | ✅ pg\_cron en Supabase | ✅ Cron, webhooks, eventos | | Webhooks | ✅ API routes | ✅ Edge Functions | ✅ | | Event-based | ❌ Limitado | ❌ Limitado | ✅ Triggers por evento, cadenas de procesos | #### Dashboards | | v0 | Lovable | Calvin | | ----------------------- | ------------------------------------ | -------------------- | ------------------------------------ | | Generar dashboards | ✅ Buena UI con React | ✅ Buena UI con React | ✅ Dashboards sobre datos reales | | Conectar a datos reales | ⚠️ Requiere integrar DB externamente | ⚠️ Solo Supabase | ✅ Conectado nativamente a tus Blocks | #### QA y revisiones de seguridad | | v0 | Lovable | Calvin | | -------------------------- | -------------------------- | ----------------------------------------------- | ------------------------------------------------- | | QA separado del desarrollo | ❌ Todo en el mismo entorno | ❌ Todo en el mismo entorno | ✅ Workspace de QA independiente del de desarrollo | | Revisiones de seguridad | ❌ No incluido | ❌ No incluido | ✅ Agentes de seguridad que revisan tu código | | Ambientes aislados | ❌ Solo preview deploys | ⚠️ Podés crear un Supabase separado manualmente | ✅ Workspaces aislados por diseño | En Calvin, el desarrollo y el QA viven en workspaces separados. Esto significa que podés testear, validar y revisar seguridad sin tocar el entorno productivo — como un equipo real de ingeniería. v0 y Lovable no tienen concepto de QA ni de revisión de seguridad. Lo que generás es lo que deployás. #### Costo y eficiencia del deployment | | v0 (Vercel serverless) | Lovable (Supabase Edge) | Calvin (Docker) | | --------------------- | ---------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------- | | Modelo de cobro | Por invocación + duración de función | Por invocación de Edge Function | Por minutos de instancia | | Concurrencia | Una invocación = un proceso aislado | Una invocación = un proceso aislado | Una instancia atiende múltiples requests en paralelo | | Cold starts | ⚠️ Sí, en cada invocación nueva | ⚠️ Sí | ✅ No. La instancia está corriendo | | Eficiencia bajo carga | ❌ 1000 requests = 1000 invocaciones facturadas | ❌ 1000 requests = 1000 invocaciones facturadas | ✅ 1000 requests = una instancia las atiende todas | | Escalabilidad | Automática pero costosa a escala | Automática pero costosa a escala | Escalado inteligente: más instancias solo cuando se necesitan | El modelo serverless de v0 y Lovable cobra por cada invocación individual. Bajo carga, esto escala en costo rápidamente. Calvin usa Docker donde una sola instancia puede atender cientos de requests en paralelo, cobrando por minuto de uso — no por cada request. Es el modelo que usan los equipos de ingeniería serios por una razón: es más predecible y más eficiente. {% endstep %} {% step %} ### 5. La diferencia no es de funcionalidad. Es de categoría. v0 y Lovable son generadores de código con preview. Calvin es una plataforma de desarrollo y operación. | Capacidad | Calvin | v0 | Lovable | | ------------------------ | -------------------------------------- | --------------------------------- | --------------------------------- | | Ideación y research | ✅ Agentes especializados | ❌ | ❌ | | Diseño UI/UX | ✅ | ✅ | ✅ | | Desarrollo frontend | ✅ | ✅ | ✅ | | Desarrollo backend | ✅ Cualquier lenguaje y runtime | ⚠️ Solo Node.js serverless | ⚠️ Solo Deno Edge Functions | | Docker / custom deps | ✅ | ❌ | ❌ | | Procesos largos | ✅ Sin límite | ❌ Max \~13 min | ❌ Max \~6.5 min | | Embeddings | ✅ Block incluido | ❌ Proveedor externo | ❌ Proveedor externo | | Vector search | ✅ Block incluido | ❌ Setup manual | ✅ pgvector en Supabase | | Reranking | ✅ Block incluido | ❌ | ❌ | | Base de datos | ✅ Block incluido | ❌ Externo | ✅ Supabase Postgres | | LLMs | ✅ Block incluido | ❌ Proveedor externo | ❌ Proveedor externo | | Emails | ✅ Block incluido | ❌ Proveedor externo | ❌ Proveedor externo | | Triggers | ✅ Cron, webhook, eventos | ✅ Cron | ✅ pg\_cron | | Deploy | ✅ Un click, infraestructura gestionada | ✅ Vercel auto-deploy | ✅ Netlify/Vercel manual | | QA en workspace separado | ✅ Workspace aislado de QA | ❌ | ❌ | | Revisiones de seguridad | ✅ Agentes de seguridad | ❌ | ❌ | | Modelo de costos | ✅ Por minuto de instancia (eficiente) | ⚠️ Por invocación (caro a escala) | ⚠️ Por invocación (caro a escala) | | Concurrencia | ✅ Una instancia, muchos requests | ❌ Un request por invocación | ❌ Un request por invocación | | Observabilidad | ✅ Monitoreo, logs, métricas | ⚠️ Básico (Vercel logs) | ⚠️ Básico (Supabase logs) | | Version control | ✅ Git nativo | ✅ Git | ✅ GitHub sync | v0 y Lovable cubren diseño + frontend + backend básico.\ Calvin cubre el ciclo completo — desde la idea hasta la operación en producción. {% endstep %} {% step %} ### 6. ¿Cuándo usar cada uno?
Usá v0 o Lovable cuando * Necesitás un prototipo rápido de UI * El proyecto es un frontend simple con backend mínimo * No tenés procesos largos ni procesamiento pesado * No necesitás embeddings, reranking, ni pipelines de datos
Usá Calvin cuando * Necesitás procesos que corren horas (scraping, ETL, pipelines) * Necesitás embeddings, vector search o reranking sin integrar terceros * Necesitás Docker con dependencias custom (Python, sharp, etc.) * Necesitás QA aislado del desarrollo y revisiones de seguridad automatizadas * Necesitás costos predecibles bajo carga, sin pagar por cada request individual * Necesitás operar en producción: monitoreo, triggers, observabilidad * Necesitás cualquier tecnología, no solo JavaScript
{% endstep %} {% step %} ### 7. La diferencia es de categoría, no de funcionalidad. Calvin no es un generador de código. Es tu plataforma de desarrollo y operación. 🔧 v0 y Lovable generan código frontend → Calvin genera soluciones end-to-end ⚡ v0 y Lovable dependen de proveedores externos → Calvin trae todo incluido como Blocks 🐳 v0 y Lovable están limitados a su stack → Calvin soporta cualquier tecnología y Docker ⏱️ v0 y Lovable mueren a los minutos → Calvin corre procesos de horas sin problemas 🔒 v0 y Lovable no tienen QA ni seguridad → Calvin tiene workspaces de QA y revisiones de seguridad 💰 v0 y Lovable cobran por invocación → Calvin cobra por minuto de instancia, más eficiente bajo carga 🧠 v0 y Lovable ejecutan código → Calvin razona, construye, despliega y opera ¿Seguís prototipando cuando podrías estar operando? {% endstep %} {% endstepper %} # UI/UX {% embed url="" %} En este video se muestra un paso a paso de cómo usar el agente de diseño. # Shopify theme En este video mostramos el paso a paso para utilizar Shopify theme desde Calvin. Se cubre el setup inicial donde se tiene que configurar la conexión entre Calvin y Shopify, y luego los comandos para traer los cambios del sitio y enviar los mismos al sitio. {% embed url="" %} # Calvin Usage Guide for VTEX IO ### Configuration Steps {% stepper %} {% step %} #### Create a Workspace in VTEX IO The first step is to create a workspace within Calvin for VTEX IO. Depending on what you want to build, you must choose between: * VTEX Store Theme workspace * VTEX Custom App workspace * VTEX Admin workspace Make sure to select the option that matches your project type.
{% endstep %} {% step %} #### Connect a Project or Template Once the workspace is created, you have two options: use our VTEX template or connect to an existing repository. In either case, navigate to settings by clicking the Settings button.
**Use a Template** You can create a new project from a base template. To do so, click the 'Use template' button and wait for the template to be added **Connect to an Existing Repository** To connect Calvin to an existing repository: 1. Navigate to the 'Repository' folder on settings.
2. Select the option to connect to a repository and complete all required fields: * GitHub * Bitbucket * GitLab 3. Choose the branch you want to work with. 4. In the settings section, define the behavior when a chat is completed: * Automatically merge into the selected branch * Create a Pull Request to the selected branch {% hint style="info" %} This configuration determines how Calvin will handle the code changes generated when a chat is completed. {% endhint %} {% endstep %} {% step %} #### Select the Correct Documentation Inside Calvin’s settings, on the 'Repository' folder, you must select the type of documentation you will be working with. Available options: * VTEX IO * VTEX Admin * VTEX Custom App It is important to select the option that corresponds to the type of workspace you previously selected. {% endstep %} {% step %} #### Perform the First VTEX Link After configuring the repository, it is necessary to run a VTEX link to your previously created VTEX IO workspace. To do this: 1. Click the 'Settings' button 2. Navigate to the 'VTEX IO' folder
3. Complete the required fields. 4. Execute the link process. **Link Verification** It is recommended to verify that the process was completed successfully: 1. Click the 'Settings' button 2. Navigate to the 'Sandbox' folder
3. Check that there are no compilation errors {% hint style="info" %} This initial link is essential because it allows Calvin to recompile the project and validate that generated changes do not contain errors. {% endhint %} {% endstep %} {% step %} #### Using Calvin in the Project Once all previous steps are completed, Calvin is ready to be used in your VTEX IO project. {% endstep %} {% endstepper %} *** ### Suggestion for Pixel Perfect Implementation To request a pixel perfect component implementation from Calvin, it is recommended to follow this workflow: 1. Attach the HTML file containing the component design. This HTML can be extracted from the UI/UX workspace. For more information on how to do this, see the UI/UX workspace documentation. 2. Include a base prompt adapted to the component you want to develop. #### Recommended Prompt ``` Create a pixel perfect implementation of the following , the design must be pixel perfect with the html file. Requirements: - Examine the html file “” - Study the existing design implementation in detail - Ensure pixel perfect accuracy to the original design - Don’t use Tailwind to make the implementation - It’s important that you use the exact same SVGs used on the html file - Study the current implementation before starting, you can find it on - To check it after a change, you must restart the vtex link and probably reload the page of the url ``` This prompt can be adapted and expanded according to the project’s needs by adding additional requirements or specific instructions. *** ### Recommendations * Always check the logs after each VTEX link. * Visually review the generated implementations before completing a chat. * Use clear and specific prompts for better results. * When developing something complex, better and faster results are usually achieved by dividing the work into smaller, manageable parts. Instead of requesting everything in a single prompt, it is recommended to modularize what you want to achieve. For example, you can first ask Calvin to build only the base structure of the component, ensuring that all elements are correctly organized and positioned. Once that structure is validated, you can then request the pixel perfect design, adjusting styles, spacing, typography, and visual details. # Magento {% embed url="" %}