Task Location & Environments

When you run a task in Cosine Desktop, you choose both where the task runs and what environment it runs in.

Where tasks run

Desktop offers three execution modes:

Local

Runs directly in your current workspace on your machine.

• Best for: Quick iterations, immediate feedback, working with local development servers
• Characteristics: Changes happen in your checked-out workspace; fastest file access
• Use when: You want to see changes immediately and work with your existing local setup

Worktree

Runs in an isolated git worktree on your machine.

• Best for: Keeping your main workspace clean, parallel tasks, experimental work
• Characteristics: Creates a separate branch and directory; doesn’t affect your current checkout
• Use when: You want isolation without the overhead of a remote machine

Remote

Runs on a cloud-hosted machine with your choice of environment.

• Best for: Heavy builds, long-running tasks, resource-intensive work, consistent team environments
• Characteristics: Ephemeral workspace created per task; access to custom environments
• Use when: You need more resources or want to use pre-configured custom environments

Environments

Environments define the runtime — the operating system, tools, and dependencies available to your task. When running remotely, you select an environment. For Local and Worktree modes, your local machine provides the runtime.

Base environments

Cosine provides five pre-built environments:

Environment	Description	Best For
Ubuntu	Full Ubuntu with Node, Python, Go	General development, most tasks
Slim	Minimal Debian, tools on-demand	Fast startup, lightweight tasks
Browser	Ubuntu + Chromium + VNC	Web testing, screenshots
Desktop	Ubuntu + KDE Plasma desktop	GUI applications, visual workflows
VS Code	Ubuntu + VS Code Server	Collaborative editing, IDE workflows

Base environments are maintained by Cosine and work immediately without setup.

Custom environments

Create custom environments when your project needs specific dependencies:

• Pre-install project-specific tools and libraries
• Bake in language versions and system packages
• Share consistent setups across your team
• Speed up task startup with pre-built images

Creating custom environments

1. Open Settings → Environments in Desktop
2. Choose how to create:
   • Create — Start from a base image and customize the Dockerfile
   • Auto-generate — Let Cosine analyze your repo and create an environment automatically
3. Select a base image (Ubuntu, Slim, Browser, Desktop, or VS Code)
4. Customize the Dockerfile with your dependencies:
   • Add RUN commands to install packages
   • Set environment variables
   • Configure system settings
5. Add secrets (encrypted key-value pairs for API keys, tokens, etc.)
6. Select a size preset and build

Auto-generate feature

Auto-generate analyses your repository to create a tailored environment:

• Detects languages, frameworks, and dependencies
• Generates an appropriate Dockerfile
• Builds the image and validates it works
• Saves to .cosine/Dockerfile in your repo

This is the fastest way to get a working custom environment.

Managing environments

From the Environments panel:

• Create/Edit — Modify the Dockerfile, base image, or secrets
• Rebuild — Rebuild after making changes
• Set as default — Use automatically for new tasks
• View logs — Debug build failures
• Delete — Remove environments you no longer need

Environment files

Custom environments save configuration files in your repository:

• .cosine/Dockerfile — Default environment
• .cosine/<name>.Dockerfile — Named custom environments
• .cosine/defaults.json — Size settings and default environment selection

Commit these files to share environments with your team.

Environment secrets

Secrets are encrypted and injected at runtime:

• Store API keys, database credentials, access tokens
• Secrets are never in Dockerfiles or build logs
• Each environment has its own secret store
• Add via the Environment Wizard or settings panel

Environment sizes

All environments (base and custom) support five sizes:

Size	CPU	Memory	Best For
XS	0.25	512 MB	Lightweight scripts
S	0.5	1 GB	Small services
M (default)	1	2 GB	Most application work
L	2	4 GB	Heavy builds, large repos
XL	4	8 GB	Demanding workloads

Each environment can have its own default size. Override per-task when needed.

Choosing configuration

For execution mode:

• Working locally, need immediate feedback → Local
• Want isolation without cloud overhead → Worktree
• Need resources or custom environments → Remote

For environment (when running Remote):

• General development → Ubuntu
• Need browser automation → Browser
• GUI apps or visual tools → Desktop
• Fast, simple tasks → Slim
• Collaborative coding → VS Code
• Project-specific needs → Custom environment

For size:

• Most work → M
• Quick tasks → S or XS
• Large builds, memory-heavy work → L or XL

Sharing environments with Cloud

Environments created in Desktop are also available in Cosine Cloud, and vice versa. The same custom environments, secrets, and builds are shared across both interfaces.

See Also

• Desktop Overview — How Desktop fits into the Cosine workflow
• Cloud Environments — Environment documentation for Cloud