Documentation

Overview

Grit is a full-stack platform consisting of three main products:

Quick Start

Get up and running with Grit Cloud in three steps.

# Or use Grit AI to generate an app first
# Then deploy it to Grit Cloud in one click

Project Structure

Grit applications follow a monorepo structure powered by Turborepo.

my-project/
├── apps/
│   ├── api/          # Go API (Gin + GORM)
│   ├── web/          # Next.js public website
│   └── admin/        # Next.js admin dashboard
├── packages/
│   └── shared/       # Shared TypeScript types & constants
├── grit.config.ts    # Grit configuration
├── turbo.json        # Turborepo task configuration
└── docker-compose.yml

Deploying a Project

Deploying to Grit Cloud is designed to be zero-configuration. Connect your repo and deploy.

Creating a New Project

1. 1.Navigate to Projects in the dashboard sidebar.
2. 2.Click New Project.
3. 3.Enter your project name, select the GitHub repository and branch.
4. 4.Optionally configure environment variables and the subdomain.
5. 5.Click Deploy. Grit Cloud will clone, build, and deploy your application.

Deployment Pipeline

Each deployment goes through these stages automatically:

Auto-Deploy on Push

Once connected, every push to your configured branch triggers a new deployment automatically. Grit Cloud sets up a GitHub webhook to listen for push events. Failed builds do not replace the current live version.

GitHub Integration

Grit Cloud uses GitHub OAuth to access your repositories. After connecting, you can:

• ✓ Select any repository for deployment
• ✓ Auto-deploy on push via webhooks
• ✓ Export AI-generated apps directly to a new GitHub repo
• ✓ View commit details for each deployment

To connect: Go to Settings → GitHub Integration → Connect GitHub. You can disconnect at any time.

Environment Variables

Store secrets and configuration securely. Environment variables are encrypted at rest and injected during the build process.

Custom Domains

By default, projects are accessible at your-project.gritcloud.app. On the Starter plan and above, you can add your own custom domain.

1. 1.Add a CNAME record pointing your domain to cname.gritcloud.app
2. 2.In your project settings, add the custom domain
3. 3.Grit Cloud provisions an SSL certificate via Let's Encrypt automatically

Logs & Monitoring

Every project comes with built-in logging and health monitoring.

Log Viewer

Access real-time logs from your project detail page by clicking Logs. You can filter by log level (info, warning, error), search log content, and enable auto-scroll for live streaming.

Health Checks

Grit Cloud monitors your application with periodic health checks. The logs page displays:

• • Current status (healthy / degraded / down)
• • Response latency
• • Uptime percentage
• • Health history over time

Bring Your Own Server (BYOS)

On the Business plan, you can connect your own servers for full control over your infrastructure.

Adding a Server

1. 1.Go to Servers in the sidebar
2. 2.Click Add Server and enter the server details: name, host, SSH port, and SSH user
3. 3.Grit Cloud will attempt to connect and verify the server
4. 4.Once verified (status: connected), you can deploy projects to this server

Grit AI Overview

Grit AI is an AI-powered application builder that generates full-stack Grit applications from natural language descriptions. Describe what you want to build, and Grit AI creates the models, API endpoints, admin panel, and frontend for you.

Sessions & Chat

Each conversation with Grit AI is a session. Sessions persist your entire conversation history and generated files.

Creating a Session

From the Workspace page, type your app description and press Enter. Grit AI creates a new session and starts generating. You can also use the + New button in the sidebar or start from a template.

Session Features

• • Fork — Create a copy of any session to experiment without affecting the original
• • Summarize — Get an AI-generated summary of your conversation
• • Search — Find sessions by title or message content
• • Delete — Remove sessions you no longer need

Visual Builder

The Visual Builder is a form-based tool that lets you define your application structure visually, without writing a single line of code or even typing a prompt. It generates a structured prompt that Grit AI uses to create your application.

How It Works

1. 1
   Name your app — Enter a name for your application at the top of the builder.
2. 2
   Define resources — Click "Add Resource" to create database models (e.g., Product, Category, Order). Each resource can have multiple fields with types like string, text, int, float, bool, date, datetime, or json.
3. 3
   Add relations — Define how resources relate to each other: belongs_to, has_many, has_one, or many_to_many.
4. 4
   Preview the prompt — The builder shows a live preview of the generated prompt at the bottom. This is the exact prompt that will be sent to Grit AI.
5. 5
   Generate — Click "Generate with AI" to create a new session with your prompt. Grit AI receives the structured prompt and generates the complete application — Go API, database models, admin panel, and frontend pages.

Example

Building an e-commerce app with the Visual Builder:

App Name: My Store

Resource: Product
  Fields: name (string), description (text), price (float), in_stock (bool)
  Relations: belongs_to Category, has_many Review

Resource: Category
  Fields: name (string), slug (string), icon (string)
  Relations: has_many Product

Resource: Review
  Fields: rating (int), comment (text), author (string)
  Relations: belongs_to Product

The builder generates a structured prompt like:

Build a Grit application called "My Store" with the following resources:

grit generate resource Product --fields "name:string, description:text, price:float, in_stock:bool" --relations "belongs_to:Category, has_many:Review"
grit generate resource Category --fields "name:string, slug:string, icon:string" --relations "has_many:Product"
grit generate resource Review --fields "rating:int, comment:text, author:string" --relations "belongs_to:Product"

Templates

Templates are pre-built application blueprints that give you a head start. Instead of writing a prompt from scratch, choose a template and Grit AI generates the full application.

Using a Template

1. 1. Go to Templates in the sidebar
2. 2. Browse by category or search by name
3. 3. Click Use Template on the template you want
4. 4. Grit AI creates a new session and starts generating from the template's prompt

Available categories include CRM, E-commerce, Blog, SaaS, Dashboard, API, and Social.

File Explorer

Each AI session can generate multiple files that form your application. The File Explorer lets you browse, view, and manage these files.

• • Tree view — Navigate the file tree with expandable directories
• • Code viewer — View file contents with syntax highlighting
• • Language detection — Files are tagged by language (TypeScript, Go, JSON, etc.)
• • Copy — Copy file contents to clipboard
• • Edit — Modify files directly in the session

Collaboration

Share your AI sessions with team members. Collaborators can view, edit, or manage sessions based on their role.

Add collaborators by email from within any session. They will gain access to the session immediately.

Export to GitHub

Once you are happy with your generated application, export it to a GitHub repository with one click.

1. 1. Make sure your GitHub account is connected (Settings → GitHub)
2. 2. In your session, click Export to GitHub
3. 3. Enter a repository name and description
4. 4. Choose public or private visibility
5. 5. Grit creates the repo and pushes all generated files

After exporting, you can deploy the repo to Grit Cloud by creating a new project linked to the repository.

Grit UI Overview

Grit UI is a component registry with 100+ production-ready React components. It's fully compatible with shadcn/ui — install any component into your project with a single command.

Components are organized into categories: marketing (hero sections, pricing cards, feature grids), e-commerce (product cards, cart items, checkout forms), and layout (sidebars, navigations, dashboards, footers).

Browse the full registry at gritcloud.app/components, or access it from within Grit AI at Grit UI in the sidebar.

Installing Components

Grit UI components are installed using the shadcn CLI. Each component is a single command.

npx shadcn@latest add https://api.gritcloud.app/r/hero-01.json

This downloads the component source code into your project at components/grit-ui/. You own the code — customize it however you like.

Component Categories

Plans & Pricing

AI Credits

Each AI generation uses one credit. Credits reset monthly based on your billing cycle. Your remaining credits are visible on the Credits page and in the Workspace header.

Managing Your Subscription

Subscriptions are managed through Stripe. From the Billing page you can:

• • View your current plan and usage
• • Upgrade or downgrade your plan
• • Access the Stripe Customer Portal to update payment methods
• • View billing history and invoices
• • Cancel your subscription

Authentication

Grit Cloud uses JWT tokens for authentication. After login, you receive an access token and a refresh token.

POST /api/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}

# Response:
{
  "access_token": "eyJhbG...",
  "refresh_token": "eyJhbG..."
}

Include the access token in all API requests:

Authorization: Bearer eyJhbG...

API Keys

For programmatic access (CI/CD, scripts, integrations), you can create API keys from Settings.

# Use an API key instead of JWT
Authorization: Bearer grit_abc123...

# API keys are prefixed with "grit_"
# The full key is shown only once — store it securely

Key Endpoints