Adding custom templates to Vibra Code

Templates define the starting point for every app a user builds. Each template is a Git repository that gets cloned into an E2B sandbox, a sequence of commands to bootstrap it, and a system prompt that tells the AI agent how to work with it. Adding your own template requires editing a single file — vibracode-backend/config.ts — and optionally building a custom E2B sandbox image.

The `Template` interface

Every template in Vibra Code implements the following TypeScript interface:

export interface Template {
  id: string;
  name: string;
  description: string;
  repository: string;
  logos: string[];
  image?: string;
  startCommands: {
    command: string;
    status: "INSTALLING_DEPENDENCIES" | "STARTING_DEV_SERVER";
    background?: boolean;
  }[];
  secrets?: Record<string, string>;
  systemPrompt: string;
}

Field reference

Field	Type	Required	Description
`id`	`string`	Yes	Unique identifier. Used as a key in Convex sessions.
`name`	`string`	Yes	Display name shown to users.
`description`	`string`	Yes	Short description shown in the template picker.
`repository`	`string`	Yes	Full GitHub URL (or `owner/repo` shorthand) to clone into the sandbox.
`logos`	`string[]`	Yes	Array of logo filenames from the `public/` directory.
`image`	`string`	No	E2B sandbox template ID. Omit to use the default E2B image.
`startCommands`	array	Yes	Ordered list of commands to run after the repo is cloned.
`secrets`	`Record<string, string>`	No	Static environment variables to write into the sandbox.
`systemPrompt`	`string`	Yes	Inline prompt string or `"FILE:filename.md"` to load from disk.

How `startCommands` work

Each entry in startCommands has three properties:

command — the shell command to run
status — the session status to display while this command runs ("INSTALLING_DEPENDENCIES" or "STARTING_DEV_SERVER")
background — if true, the command runs in the background (non-blocking). Use this for long-lived processes like dev servers.

Commands run in order. The session moves to RUNNING status after all non-background commands complete.

Existing templates as reference

The built-in templates show the range of possible configurations:

export const templates: Template[] = [
  {
    id: "expo",
    name: "Expo React Native",
    description:
      "Build cross-platform mobile apps with Expo SDK, TypeScript, and NativeWind styling.",
    repository: "https://github.com/sa4hnd/expo-template",
    logos: ["expo.svg"],
    image: "YOUR_E2B_TEMPLATE_ID",
    startCommands: [
      {
        command:
          "echo fs.inotify.max_user_watches=524288 >> /etc/sysctl.conf && sysctl -p && npx expo start --tunnel --port 3000",
        status: "STARTING_DEV_SERVER",
        background: true,
      },
    ],
    systemPrompt: "FILE:system-prompt.md",
  },
  {
    id: "nextjs",
    name: "Next.js",
    description:
      "Build scalable web applications with server-side rendering, static site generation, and API routes",
    repository: "https://github.com/superagent-ai/e2b-nextjs",
    logos: ["nextjs.svg"],
    startCommands: [
      { command: "npm i", status: "INSTALLING_DEPENDENCIES" },
      { command: "npm run dev", status: "STARTING_DEV_SERVER", background: true },
    ],
    systemPrompt:
      "# GOAL\nYou are a helpful assistant building a NextJS app.\n" +
      "- The NextJS dev server is running on port 3000.\n" +
      "- ShadCN UI is installed with all the ShadCN components.\n",
  },
  // ...
];

The Shopify template uses secrets to write a static SESSION_SECRET into the sandbox environment, and uses multiple INSTALLING_DEPENDENCIES steps to install both npm packages and the Shopify CLI globally before starting the dev server.

Adding a new template

Create or find a starter repository

Your template needs a public GitHub repository. It should be a working app skeleton that can be cloned, installed, and started with a small number of shell commands.If you’re forking an existing template, make sure the repository is publicly accessible or that your E2B sandbox has credentials to clone it.

Add your logo assets

Place logo files (SVG or JPEG) in vibracode-backend/public/. Reference them by filename in the logos array. Multiple logos are displayed as a stack in the template picker.

cp my-framework-logo.svg vibracode-backend/public/my-framework.svg

Write the template entry in config.ts

Open vibracode-backend/config.ts and add your template to the templates array:

{
  id: "remix",
  name: "Remix",
  description:
    "Build full-stack web apps with nested routing, loaders, and actions.",
  repository: "https://github.com/remix-run/remix/tree/main/templates/remix",
  logos: ["remix.svg"],
  startCommands: [
    {
      command: "npm install",
      status: "INSTALLING_DEPENDENCIES",
    },
    {
      command: "npm run dev",
      status: "STARTING_DEV_SERVER",
      background: true,
    },
  ],
  systemPrompt:
    "# GOAL\nYou are a helpful assistant building a Remix app.\n" +
    "- The Remix dev server is running on port 3000.\n" +
    "- Use Remix loaders and actions for data fetching.\n" +
    "- TailwindCSS is installed.\n",
},

Write a system prompt

Your system prompt should tell the AI agent which stack it is working in and any important constraints. At minimum, include the dev server port, installed packages, and any patterns you want enforced.For long prompts, use the file reference syntax:

systemPrompt: "FILE:remix-prompt.md",

Then create vibracode-backend/remix-prompt.md with the full prompt content. See Customizing AI system prompts for guidance on writing effective prompts.

Restart the backend

cd vibracode-backend
npm run dev

Your new template will appear in the template picker immediately.

Building a custom E2B sandbox

By default, E2B sandboxes start from a standard base image. If your template needs pre-installed system dependencies (compilers, runtimes, native tools), build a custom E2B image and set its ID in the image field.

Install the E2B CLI

npm install -g @e2b/cli
e2b auth login

Create a Dockerfile

Create a directory for your template (for example, vibracode-backend/e2b-remix-template/) and add a Dockerfile:

FROM e2bdev/code-interpreter:latest

# Install any system dependencies your template needs
RUN apt-get update && apt-get install -y \
    build-essential \
    python3

# Pre-install Node.js dependencies globally if needed
RUN npm install -g remix

Build the E2B template

cd vibracode-backend/e2b-remix-template
e2b template build

E2B will print a template ID when the build completes.

Set the template ID in config.ts

Copy the template ID from the E2B CLI output and paste it into the image field of your template entry:

{
  id: "remix",
  image: "abc123def456",  // Your E2B template ID
  // ...
}

You do not need a custom E2B image for most web templates. The default E2B image includes Node.js, npm, Python, and common build tools. Only build a custom image if your template has unusual native dependencies.

E2B template builds count against your E2B usage. Build templates infrequently and reuse the same image ID across deploys unless the base dependencies change.

Deployment

Customization

Contributing

Adding custom templates to Vibra Code

The `Template` interface

Field reference

How `startCommands` work

Existing templates as reference

Adding a new template

Building a custom E2B sandbox

Build docs developers (and LLMs) love

Deployment

Customization

Contributing

​The Template interface

​Field reference

​How startCommands work

​Existing templates as reference

​Adding a new template

​Building a custom E2B sandbox

Build docs developers (and LLMs) love

The `Template` interface

Field reference

How `startCommands` work

Existing templates as reference

Adding a new template

Building a custom E2B sandbox