Remote Workspaces - Best Practices

Proven tips and workflows to get the most out of remote workspaces in Factory

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

1. Smart Setup Script Practices

Practice	Why it matters	How to do it
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
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
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
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
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
Minimize heavy operations	Long builds slow down workspace creation.	Focus on essential setup; defer optional tools to manual installation later

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.

---

2. Workflow Patterns That Scale

Spin-Up-Per-Task

Treat remote sessions as disposable: create one per ticket or PR, then archive when merged.
Benefits: perfect isolation, zero “works on my machine” drift.

Parallel Environments

Need to test multiple branches? Launch two separate sessions; switch context without killing processes.

---

3. Team Collaboration Tips

Tip	Details
Name workspaces clearly	Name workspaces according to the tracked repository, e.g. factory-mono to work on the factory-mono GitHub repo.
Document entry commands	Add an AGENTS.md file with common tasks (npm run dev, pytest). Droid automatically reads this file.

5. Troubleshooting at a Glance

Symptom	Resolution
Rebuild is slow	Verify .dockerignore, cache heavy installs in image, use lighter base.
Git asks for credentials	Ensure repository integration is enabled in Integrations → Repositories.
Out-of-disk errors	Prune package caches (npm cache clean --force) or rebuild workspace.

Following these practices keeps your remote workspaces fast, secure, and collaborative—so you can focus on shipping code, not configuring machines.