Cloud Templates

Cloud templates let you code anywhere without the "works on my machine" dance. Each template is a pre-configured environment that lives in the cloud, boots in seconds and can be customized to run setup commands.

Why use cloud templates?

Installation & usage

A cloud template is a fully-configured, on-demand development environment that lives in the cloud. Cloud templates give you the same tools and dependencies you'd expect locally, so you can build, test, and run code directly from Factory.

System requirements

• A repository enabled in Factory
• User role or higher to create cloud templates

1. 1
   Open Cloud Templates Settings

   1. 1
      In Factory, click the Settings icon from the left sidebar.
   2. 2
      Select Cloud Templates.
2. 2
   Create a New Cloud Template

   1. 1
      Click Create Template.
   2. 2
      Enter the repository you want to use.
   3. 3
      Give your template a friendly name (e.g., "frontend-template").
   4. 4
      (Optional) Configure a setup script to run during template initialization.
   5. 5
      Click Create.

   Note

   Factory clones your repo and prepares the environment. This can take a minute for large projects.

3. 3
   Verify Template Ready

   The new template appears in the list with a status indicator. Once it shows Ready, you can use it from any session.

Launching a cloud template inside a session

1. 1
   Open or Start a Session

   Join any Factory session as usual.

2. 2
   Connect to Cloud Machine

   1. 1
      On the session start page, click the Machine Connection button.
   2. 2
      Choose Remote tab.
   3. 3
      Select the template you created earlier.
   4. 4
      Factory attaches the cloud template to your session.

   

3. 3
   Confirm Connection

   A green indicator and remote working directory appear on the top-right next to your profile dropdown menu. You're now interacting with the cloud template.

Everyday usage

npm run dev
pytest
git status

Setup script

The setup script is a shell script that Factory runs during template creation, after your repository is cloned and before the template is activated. Use this feature to set up your template and give droid tools to work with your codebase.

How to define a setup script

1. 1
   In the modal for template creation, in the "Setup Script (Optional)" section, add your initialization script. You can write a multi-line bash script with all the commands you need.
2. 2
   Submit. The script runs in the repo root exactly as provided. Add set -euo pipefail at the top of your script if you want strict error handling. Script failures will stop the build.
3. 3
   Keep your script non‑interactive and idempotent. Write commands that can be safely re-run.
4. 4
   Review build logs if anything fails to see detailed output from your script execution.

Examples:

Node.js (Next.js):

#!/usr/bin/env bash
set -euo pipefail
 
npm ci
npm run build

PNPM monorepo:

#!/usr/bin/env bash
set -euo pipefail
 
pnpm -w i
pnpm -w build

Python:

#!/usr/bin/env bash
set -euo pipefail
 
pip install -r requirements.txt
pytest -q

Multi-language project:

#!/usr/bin/env bash
set -euo pipefail
 
# Install Node.js dependencies
npm ci
 
# Install Python dependencies
pip install -r requirements.txt
 
# Run setup script
bash ./scripts/setup.sh

What happens under the hood:

• The script executes after repository cloning, inside the build container at the repo root.
• Environment variables specified in template settings are available during script execution.
• Errors are surfaced clearly (e.g., Setup script failed: ...) for quick fixes.

Setup script troubleshooting tips

Best practices

Cloud templates let you spin up consistent, production-ready development environments in seconds. Below are field-tested practices that keep templates fast, predictable, and team-friendly.

Smart setup script practices

Tip: Test your setup script locally first. The script runs with bash at the repo root, and you can add set -euo pipefail for strict error handling.

Workflow patterns that scale

Team collaboration tips

Troubleshooting

Even the smoothest cloud template can hit a snag. This section walks you through the quickest fixes for the most common cloud template issues.