Skip to main content
A cloud workspace has a main development environment with your connected GitHub repositories. Set up the dependencies and services there; new tasks normally run in separate forks, or copies, of that environment. Your computer can be off while cloud agents work.

​
Two ways to set up

Every cloud workspace starts the same way: sign in at twill.ai/login, choose Create cloud workspace, and install the Twill GitHub App on your repositories. What differs is which agent configures the environment:

From a local project

Your local agent reproduces the setup that already works on your computer. Best when the app runs locally.

From the cloud

A cloud agent reads your repositories and sets everything up from scratch.

​
From a local project

1

Pick the project

In the GitHub step of workspace creation, choose Start from a local project. GitHub opens with that project’s repositories preselected; grant access to all of them.
2

Start setup

Continue through secrets and integrations, then choose Start setup. A setup chat opens on the project’s computer, under that project. The computer must be online with a connected agent.
3

Let the local agent configure the cloud

The agent uses your folders as a reference and connects to the cloud environment over temporary SSH to install dependencies, configure services, and verify the apps. It asks before reading or copying any local environment values, even with Approve for me.
The report ends with a workspace card: Open connects your terminal, VS Code, or Cursor to the cloud environment, and Configure secrets opens the environment settings. You can also start this from any local project chat: “Set up a cloud workspace to run this project.” Setup only prepares the environment; use Handoff to send work to a cloud agent.

​
From the cloud

1

Connect repositories

Create the workspace and install the GitHub App on the repositories your project needs.
2

Start setup

Add secrets and integrations if you have them, then choose Start setup, or Skip for now and come back later.
3

Check the report

A cloud agent reads your repositories, installs dependencies, configures services, and checks that your apps run. It reports what started, what passed, and which credentials are missing.

​
Update the environment

To update or repair the shared environment later, start a cloud task with Fork off:

​
Environment variables & secrets

Open Settings → Environment to configure:
  • Global variables, made available to cloud tasks.
  • Per-repository variables, written to that repository’s .env file on the VM.
Add variables individually or paste .env contents into a field. Review the values and choose Save. Saved secrets are encrypted at rest.

​
Import from a local folder

For connected local projects matching a workspace repository, Use .env suggests .env, .env.local, .env.dev, and .env.development files at the selected folder root. The linked project is suggested first during setup. File discovery happens on the computer. Choosing Use reads the selected file into the editor for review; Save sends the values to Twill. Selecting a project alone doesn’t copy its secrets. Values copied directly by a setup agent over SSH stay on the VM and aren’t automatically saved in these settings. Record reproducible setup commands and save managed secrets here so you can rebuild the environment if the VM is replaced.

​
Live previews

When a cloud task has a running app, open its preview and select the service port to try the result. A preview needs a healthy server in that task’s environment; check service logs if it doesn’t load. Keep the server running for later review. Previews stay available while the task’s fork exists; see Fork lifecycle. Local previews open on your computer instead.

​
Fork lifecycle

Each cloud task runs in its own fork of the workspace environment, created on its first run and reused by later messages in the same task. CLI scratch forks follow the same rules. A running agent counts as activity, so a fork doesn’t pause mid-run. After a fork is deleted, the next message in the task starts from a fresh fork of the current workspace environment: the conversation is kept, but uncommitted changes, installed packages, and data that only existed in the old fork are lost. Push branches you want to keep. The workspace VM pauses after 15 minutes of inactivity and resumes when a task, setup run, or SSH connection needs it. It is never deleted automatically and has no maximum lifetime. Tasks started with Fork off run directly on the workspace VM.

​
Inspect the environment

Use Open on the Environment page, or the task’s environment controls, to access the sandbox. Where SSH is available, Twill offers a temporary command for your terminal or an editor with Remote-SSH support. The default access duration is 60 minutes. Connected repositories live at /root/workspace/{owner}/{repo}. The CLI also provides workspace SSH and named scratch forks. Choose VM size in environment settings: Small is available on Free, Medium on Pro, and Large on Max. Custom snapshots require Pro or Max. See Pricing. Resizing provisions a fresh workspace VM at the new size and re-clones your connected repositories (with their environment variables), so it can take a few minutes. Tasks that are already running keep their current sandbox; new tasks start from the resized VM. Anything installed by hand on the old VM is not carried over. Sizes can move up or down, as long as your plan covers the target size.