Skip to main content

The development environment

Think of the module's development machine as a small computer in the cloud. It has a filesystem, a shell, installed tools, and running processes. The browser-based editor is your way into that computer; the application you are developing runs there, not on your laptop.

What you can run​

The base environment is a minimal Debian Linux system with Node.js 22, Python 3, Git, and package-management tools. It also includes a headless browser and Puppeteer for browser-based checks.

You can install packages, run scripts, build applications, start development servers, and use command-line tools. Other languages and frameworks may need additional installation. Choose tools compatible with the Linux environment and the machine's available memory, storage, and compute capacity: a development machine is not unlimited infrastructure.

Ask the agent to inspect the environment and explain the requirements before starting a particularly demanding build.

Your workspace​

The source-code workspace is /workspace. It is also the root of the module's Git checkout, so files you see in the Explorer are the same files available to your terminals and the agent.

Each project collaborator has their own development workspace for a module. Your editor and agent use your workspace; Git is how you share code with other collaborators. A file saved in your workspace does not automatically appear in somebody else's checkout.

Workspace files are stored on a persistent volume. This lets you return to your work after the machine stops, but persistence is not a substitute for committing and pushing important work.

What survives a restart?​

ItemWhat to expect
Saved files under /workspacePreserved when the machine restarts normally. This includes uncommitted files and local Git history.
Changes still unsaved in an editor tabNot yet on the workspace disk. Save them before restarting or leaving.
Running servers, shells, and in-memory stateStopped when the machine is replaced. Start the processes again.
System-wide changes outside persistent storageDo not rely on them surviving a fresh machine. Keep setup reproducible.
A separate deploymentHas its own lifecycle; restarting the dev machine does not redeploy it.

Record dependencies in the application's manifests and lockfiles, and keep repeatable setup instructions or scripts in the repository. Workspace-local dependencies can survive a normal restart, but a fresh checkout or deployment still needs to install them.

Starting and reconnecting​

Opening a module prepares or reconnects to your development machine. The editor shows its status while this happens. Development machines can stop when no longer in use, and previews stop with them; they are not intended to host an always-on application.

If a connection is interrupted, let the editor reconnect before issuing more commands. Check any long-running task rather than assuming it completed. Use Deployments when the application needs to remain available independently of your development session.

Restart versus reset​

Open Dev Machine → Overview for the machine controls.

Restart machine starts a fresh machine while preserving the workspace volume. It stops processes, including terminals and development servers. Save editor changes first, then check your startup commands or restart the tools you need.

Reset machine destroys both the machine and its workspace volume, then starts again from the module's repository. This is a destructive recovery action, not a routine restart.

Before resetting

Commit and push everything you need to keep. Local commits that have not been pushed are lost too. Back up required untracked or ignored files separately, because they are not protected by pushing a branch. Reset cannot recover them afterwards.

Continue with Code, terminals, and startup commands to work in the environment.