Skip to content

Commit 09c1cc5

Browse files
factory-octavianfactory-octavian
committed
add back
1 parent 5013789 commit 09c1cc5

File tree

9 files changed

+394
-50
lines changed

9 files changed

+394
-50
lines changed

‎docs/docs.json‎

Lines changed: 11 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,17 @@
8585
"group": "App",
8686
"pages": [
8787
"web/getting-started/overview",
88-
"web/getting-started/quickstart"
88+
"web/getting-started/quickstart",
89+
{
90+
"group": "Cloud Templates",
91+
"pages": [
92+
"web/machine-connection/cloud-templates/index",
93+
"web/machine-connection/cloud-templates/installation-and-usage",
94+
"web/machine-connection/cloud-templates/setup-script",
95+
"web/machine-connection/cloud-templates/best-practices",
96+
"web/machine-connection/cloud-templates/troubleshooting"
97+
]
98+
}
8999
]
90100
},
91101
"pricing"
@@ -518,46 +528,6 @@
518528
"source": "/user-guides/memory/understanding-memory",
519529
"destination": "/cli/user-guides/become-a-power-user"
520530
},
521-
{
522-
"source": "/user-guides/remote-workspaces",
523-
"destination": "/web/getting-started/overview"
524-
},
525-
{
526-
"source": "/user-guides/remote-workspaces/best-practices",
527-
"destination": "/web/getting-started/overview"
528-
},
529-
{
530-
"source": "/user-guides/remote-workspaces/custom-commands",
531-
"destination": "/web/getting-started/overview"
532-
},
533-
{
534-
"source": "/user-guides/remote-workspaces/installation-and-usage",
535-
"destination": "/web/getting-started/overview"
536-
},
537-
{
538-
"source": "/user-guides/remote-workspaces/troubleshooting",
539-
"destination": "/web/getting-started/overview"
540-
},
541-
{
542-
"source": "/web/machine-connection/remote-workspaces/index",
543-
"destination": "/web/getting-started/overview"
544-
},
545-
{
546-
"source": "/web/machine-connection/remote-workspaces/installation-and-usage",
547-
"destination": "/web/getting-started/overview"
548-
},
549-
{
550-
"source": "/web/machine-connection/remote-workspaces/setup-script",
551-
"destination": "/web/getting-started/overview"
552-
},
553-
{
554-
"source": "/web/machine-connection/remote-workspaces/best-practices",
555-
"destination": "/web/getting-started/overview"
556-
},
557-
{
558-
"source": "/web/machine-connection/remote-workspaces/troubleshooting",
559-
"destination": "/web/getting-started/overview"
560-
},
561531
{
562532
"source": "/user-guides/sessions-in-factory/chat-interface",
563533
"destination": "/cli/getting-started/overview"

‎docs/factory-docs-map.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -866,32 +866,32 @@ This map uses a hierarchical structure:
866866
- Reset Factory Bridge
867867
- Getting Additional Help
868868

869-
### [Remote Workspaces - Best Practices](https://docs.factory.ai/web/machine-connection/remote-workspaces/best-practices)
869+
### [Cloud Templates - Best Practices](https://docs.factory.ai/web/machine-connection/cloud-templates/best-practices)
870870

871871
- 1. Smart Setup Script Practices
872872
- 2. Workflow Patterns That Scale
873873
- 3. Team Collaboration Tips
874874
- 5. Troubleshooting at a Glance
875875

876-
### [Remote Workspaces](https://docs.factory.ai/web/machine-connection/remote-workspaces)
876+
### [Cloud Templates](https://docs.factory.ai/web/machine-connection/cloud-templates)
877877

878-
- Why use remote workspaces?
878+
- Why use cloud templates?
879879
- Get Started
880880
- More to Explore
881881

882-
### [Remote Workspaces – Installation & Usage](https://docs.factory.ai/web/machine-connection/remote-workspaces/installation-and-usage)
882+
### [Cloud Templates – Installation & Usage](https://docs.factory.ai/web/machine-connection/cloud-templates/installation-and-usage)
883883

884884
- System Requirements
885885
- Launching a Remote Workspace inside a Session
886886
- Everyday Usage
887887
- Troubleshooting & Help
888888

889-
### [Remote Workspaces – Setup Script](https://docs.factory.ai/web/machine-connection/remote-workspaces/setup-script)
889+
### [Cloud Templates – Setup Script](https://docs.factory.ai/web/machine-connection/cloud-templates/setup-script)
890890

891891
- 1. How to define a setup script
892892
- 2. Troubleshooting Tips
893893

894-
### [Remote Workspaces – Troubleshooting](https://docs.factory.ai/web/machine-connection/remote-workspaces/troubleshooting)
894+
### [Cloud Templates – Troubleshooting](https://docs.factory.ai/web/machine-connection/cloud-templates/troubleshooting)
895895

896896
- Quick Reference
897897
- 1. Workspace Creation Issues

‎docs/web/getting-started/overview.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Overview
33
sidebarTitle: Overview
44
description: If it can be done on a computer, it can be done with a Droid.
5-
keywords: ['factory app', 'desktop app', 'droid', 'factory bridge', 'bridge', 'remote workspaces', 'cloud workspaces', 'local machine', 'download', 'install', 'mac', 'windows', 'ai coding', 'coding assistant']
5+
keywords: ['factory app', 'desktop app', 'droid', 'factory bridge', 'bridge', 'cloud templates', 'cloud workspaces', 'local machine', 'download', 'install', 'mac', 'windows', 'ai coding', 'coding assistant']
66
---
77

88
<Note>
@@ -58,5 +58,5 @@ Install, sign in, set your working directory, and start building. [Try the quick
5858
</CardGroup>
5959

6060
<Note>
61-
**Looking for Factory Bridge or Remote Workspaces?** The Factory App replaces both. The desktop app connects directly to your local machine with Droid built-in — no separate applications or cloud workspaces needed.
61+
**Looking for Factory Bridge or Cloud Templates?** The Factory App replaces both. The desktop app connects directly to your local machine with Droid built-in — no separate applications or cloud templates needed.
6262
</Note>

‎docs/web/getting-started/quickstart.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Quickstart"
33
description: "Get up and running with the Factory App in 5 minutes"
4-
keywords: ['quickstart', 'getting started', 'factory app', 'desktop app', 'droid', 'factory bridge', 'bridge', 'remote workspaces', 'setup', 'install', 'download', 'local machine', 'working directory']
4+
keywords: ['quickstart', 'getting started', 'factory app', 'desktop app', 'droid', 'factory bridge', 'bridge', 'cloud templates', 'setup', 'install', 'download', 'local machine', 'working directory']
55
---
66

77
<Note>

‎docs/web/machine-connection/cloud-templates/best-practices.mdx‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: Cloud Templates - Best Practices
3+
description: Proven tips and workflows to get the most out of cloud templates in Factory
4+
---
5+
6+
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.
7+
8+
## 1. Smart Setup Script Practices
9+
10+
| Practice | Why it matters | How to do it |
11+
| ---------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
12+
| **Order commands by dependency** | Later commands may depend on earlier installs. | Run package installation first: `npm ci && npm run build` or `pip install -r requirements.txt && pytest -q` |
13+
| **Use exact package managers** | Consistent lockfiles prevent version drift. | Use `npm ci` (not `npm install`), `pnpm -w i`, or `pip install -r requirements.txt` for reproducible builds |
14+
| **Add error handling** | Stops build on first failure, saves debugging time. | Start your script with `#!/usr/bin/env bash` and `set -euo pipefail` for proper error handling |
15+
| **Make scripts executable early** | Avoid permission errors mid-build. | Add `chmod +x ./scripts/setup.sh && bash ./scripts/setup.sh` or use `bash ./scripts/setup.sh` directly |
16+
| **Keep scripts idempotent** | Re-running setup shouldn't break things. | Use flags like `pip install --no-deps` or check for existing files before creating them |
17+
| **Minimize heavy operations** | Long builds slow down template creation. | Focus on essential setup; defer optional tools to manual installation later |
18+
19+
> **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.
20+
21+
22+
---
23+
24+
## 2. Workflow Patterns That Scale
25+
26+
<AccordionGroup>
27+
28+
<Accordion title="Spin-Up-Per-Task">
29+
Treat remote sessions as disposable: create one per ticket or PR, then archive when merged.
30+
**Benefits:** perfect isolation, zero “works on my machine” drift.
31+
</Accordion>
32+
33+
<Accordion title="Parallel Environments">
34+
Need to test multiple branches? Launch two separate sessions; switch context without killing processes.
35+
</Accordion>
36+
37+
</AccordionGroup>
38+
39+
---
40+
41+
## 3. Team Collaboration Tips
42+
43+
| Tip | Details |
44+
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
45+
| **Name templates clearly** | Name templates according to the tracked repository, e.g. `factory-mono` to work on the `factory-mono` GitHub repo. |
46+
| **Document entry commands** | Add an `AGENTS.md` file with common tasks (`npm run dev`, `pytest`). Droid automatically reads this file. |
47+
48+
## 5. Troubleshooting at a Glance
49+
50+
| Symptom | Resolution |
51+
| ---------------------------- | ---------------------------------------------------------------------------- |
52+
| **Rebuild is slow** | Verify `.dockerignore`, cache heavy installs in image, use lighter base. |
53+
| **Git asks for credentials** | Ensure repository integration is enabled in **Integrations → Repositories**. |
54+
| **Out-of-disk errors** | Prune package caches (`npm cache clean --force`) or rebuild template. |
55+
56+
Following these practices keeps your cloud templates fast, secure, and collaborative—so you can focus on shipping code, not configuring machines.

‎docs/web/machine-connection/cloud-templates/index.mdx‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Cloud Templates
3+
description: Spin-up instant, cloud-hosted templates that mirror your local dev setup. No install required
4+
---
5+
6+
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.
7+
## Why use cloud templates?
8+
9+
| Benefit | What it means for you |
10+
| ----------------- | ------------------------------------------------------------------------------------------------------- |
11+
| **Zero setup** | Open a session and start coding; no local installs or VM juggling. |
12+
| **Consistency** | Every teammate (and CI job) runs the _exact_ same environment. |
13+
| **Speed** | Heavy builds run on powerful cloud CPUs; your laptop fan stays silent. |
14+
| **Isolation** | Experiments live in disposable templates, keeping your local machine clean. |
15+
| **Collaboration** | Share a template link; reviewers jump into the _live_ environment with code and ports already running. |
16+
17+
## Get Started
18+
19+
<CardGroup cols={2}>
20+
21+
<Card title="1 · Create a Template" icon="rocket" href="/web/machine-connection/cloud-templates/installation-and-usage">
22+
Use the **Settings → Session** page to spin up a new cloud template from your repository.
23+
</Card>
24+
25+
26+
<Card title="2 · Add setup script" icon="toolbox" href="/web/machine-connection/cloud-templates/setup-script">
27+
Configure a setup script to run during template creation.
28+
</Card>
29+
30+
<Card title="3 · Follow Best Practices" icon="lightbulb" href="/web/machine-connection/cloud-templates/best-practices">
31+
Optimize performance, cost, and team workflows with proven tips.
32+
</Card>
33+
34+
<Card title="4 · Troubleshoot Like a Pro" icon="bug" href="/web/machine-connection/cloud-templates/troubleshooting">
35+
Quickly resolve provisioning, connection issues.
36+
</Card>
37+
38+
</CardGroup>
39+
40+
---
41+
42+
### More to Explore
43+
44+
- [**Installation & Usage** – step-by-step setup guide](/web/machine-connection/cloud-templates/installation-and-usage)
45+
46+
- [**Best Practices** – performance, cost, collaboration](/web/machine-connection/cloud-templates/best-practices)
47+
48+
- [**Troubleshooting** – common fixes & FAQs](/web/machine-connection/cloud-templates/troubleshooting)
49+
50+
Ready? Head to **Settings → Templates** and launch your first cloud template. Happy coding!

‎docs/web/machine-connection/cloud-templates/installation-and-usage.mdx‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Cloud Templates – Installation & Usage
3+
description: Set up, connect to, and use Cloud Templates inside Factory sessions
4+
---
5+
6+
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.
7+
8+
<Note>
9+
To get the most out of cloud templates, configure environment variables and a setup script during template creation. The setup script installs dependencies and prepares your development environment automatically, ensuring every team member has an identical setup.
10+
</Note>
11+
12+
## System Requirements
13+
14+
- A repository enabled in Factory
15+
- Manager role or higher to create cloud templates
16+
17+
<Steps>
18+
19+
<Step title="Open Session Settings">
20+
1. In Factory, click the **Settings** icon from the left sidebar.
21+
2. Select **Session**.
22+
3. Scroll down to **Cloud Templates**.
23+
</Step>
24+
25+
<Step title="Create a New Cloud Template">
26+
1. Click **Create Template**.
27+
2. Enter the repository you want to use.
28+
3. Give your template a friendly name (e.g., “frontend-template”).
29+
4. (Optional) Configure a setup script to run during template initialization.
30+
5. Click **Create**.
31+
<Note>
32+
Factory clones your repo and prepares the environment—this can take a minute for large projects.
33+
</Note>
34+
</Step>
35+
36+
<Step title="Verify Template Ready">
37+
The new template appears in the list with a status indicator. Once it shows **Ready**, you can use it from any session.
38+
</Step>
39+
40+
</Steps>
41+
42+
---
43+
44+
## Launching a Cloud Template inside a Session
45+
46+
<Steps>
47+
48+
<Step title="Open or Start a Session">
49+
Join any Factory session as usual.
50+
</Step>
51+
52+
<Step title="Connect to Cloud Machine">
53+
1. On the session start page, click the Machine Connection button.
54+
2. Choose **Remote** tab.
55+
3. Select the template you created earlier.
56+
4. Factory attaches the cloud template to your session.
57+
58+
<Frame>
59+
![machine-connection-start.gif](/images/web/machine-connection-start.gif)
60+
</Frame>
61+
</Step>
62+
63+
<Step title="Confirm Connection">
64+
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.
65+
</Step>
66+
67+
</Steps>
68+
69+
---
70+
71+
## Everyday Usage
72+
73+
<CardGroup cols={2}>
74+
75+
<Card title="Run CLI Commands" icon="terminal">
76+
Use the **Terminal** toolkit to execute commands like:
77+
<pre>npm run dev
78+
pytest
79+
git status</pre>
80+
Output streams live into chat and logs.
81+
</Card>
82+
83+
<Card title="Edit & Save Files" icon="file-code">
84+
Open files from the repo, make changes, and save.
85+
Files persist in the cloud template and can be committed upstream when ready.
86+
</Card>
87+
88+
<Card title="Auto-Save Controls" icon="save">
89+
Auto-save is disabled by default—enable it from the **Session Settings** panel whenever you want live file syncing.
90+
</Card>
91+
92+
</CardGroup>
93+
94+
---
95+
96+
## Troubleshooting & Help
97+
98+
<AccordionGroup>
99+
100+
<Accordion title="Can't connect from session">
101+
Ensure you:
102+
1. Selected **Remote Machine** (not Local).
103+
2. Refresh the page, or try again in a different session
104+
</Accordion>
105+
106+
</AccordionGroup>
107+
108+
<Card title="Need More Help?" icon="life-ring" href="/web/machine-connection/cloud-templates/troubleshooting">
109+
Visit the full Cloud Template Troubleshooting Guide
110+
</Card>

0 commit comments

Comments
 (0)