Environments

When you create a task in Cosine Cloud, you select an environment — a containerized runtime with the operating system, tools, and dependencies needed for your project.

Base environments

Cosine provides five pre-built environments that work immediately without configuration.

Ubuntu

The default environment for most engineering work.

• Best for: General-purpose development, code edits, builds, tests, and shell commands
• Includes: Ubuntu with Node.js, Python, Go, and common development tools pre-installed
• Use when: You want a full Linux environment with broad language support

Slim

A lightweight alternative to Ubuntu.

• Best for: Quick tasks, lightweight scripts, smaller repositories
• Includes: Minimal Debian base with tools installed on-demand
• Use when: You want faster startup and don’t need the full Ubuntu toolchain

Browser

For web testing and browser automation.

• Best for: Browser testing, screenshots, form flows, web UI interaction
• Includes: Ubuntu base plus Chromium, Xvfb, and VNC for remote browser viewing
• Use when: Your task needs to open and interact with web pages

Desktop

A full graphical desktop environment.

• Best for: Graphical workflows, desktop applications, rich visual tasks
• Includes: Ubuntu with KDE Plasma desktop and VNC remote access
• Use when: You need to view or interact with GUI applications remotely

VS Code

Browser-based editor environment.

• Best for: Editor-first workflows, collaborative coding, IDE-style remote work
• Includes: Ubuntu with VS Code Server pre-installed and accessible via browser
• Use when: You want to watch or collaborate on code changes in real-time

Custom environments

Create custom environments when your project needs specific dependencies, tools, or configurations that the base environments don’t include.

Why use custom environments

• Project-specific dependencies: Pre-install libraries, frameworks, or system packages your project requires
• Consistency: Ensure every task runs with identical tooling and versions
• Faster task startup: Dependencies are baked into the image, not installed at runtime
• Complex setups: Configure databases, services, or multi-step environment preparation

Creating custom environments

Custom environments are created via the Environment Wizard in settings:

1. Navigate to Project Settings → Environments -> Configure Environments
2. Click Create or Auto-generate
3. Select a base image (Ubuntu, Slim, Browser, Desktop, or VS Code)
4. Customize the Dockerfile with your dependencies
5. Add environment secrets if needed (API keys, tokens, etc.)
6. Select a size preset and build

The built environment becomes available for tasks in both Desktop and Cloud.

Auto-generate environments

The Auto-generate feature analyses your repository and creates an environment tailored to your project:

• Inspects the codebase to detect languages and frameworks
• Generates a Dockerfile with appropriate dependencies
• Builds and validates the environment works at runtime
• Saves the Dockerfile within the .cosine folder in your repository

Managing environments

From the Environments settings panel you can:

• View all environments with their build status and base image
• Edit an environment to modify its Dockerfile or secrets
• Rebuild an environment after making changes
• Set as default to use it automatically for new tasks
• Delete environments you no longer need
• View build logs to debug build failures

Environment files

When you create custom environments, Cosine saves configuration in your repository:

• .cosine/Dockerfile — The default environment Dockerfile
• .cosine/<name>.Dockerfile — Named environment Dockerfiles
• .cosine/defaults.json — Size preferences and default environment setting

These files can be committed to version control to share environments with your team.

Environment secrets

Secrets are encrypted key-value pairs injected into environments at runtime. They’re useful for:

• API keys and access tokens
• Database credentials
• Private registry authentication
• Any sensitive configuration

Secrets are always encrypted stored per-environment. They are never exposed in build logs or Dockerfiles.

Environment sizes

All environments (base and custom) can run at different resource tiers:

Size	CPU	Memory	Best for
XS	0.25	512 MB	Lightweight tasks, quick scripts
S	0.5	1 GB	Small services, focused edits
M	1	2 GB	Default for most application work
L	2	4 GB	Heavier builds, larger test suites
XL	4	8 GB	Largest repositories, demanding workloads

Each environment can have its own default size. When creating a task, you can override the size for that specific run.

Choosing the right environment

Start with base environments:

• General development → Ubuntu
• Need browser access → Browser
• GUI applications → Desktop
• Fast, minimal tasks → Slim
• Collaborative editing → VS Code

Create custom environments when:

• Your project requires specific language versions or system packages
• You want faster task startup with pre-installed dependencies
• You need consistency across team members
• The base environments don’t include tools your project needs

Size guidelines:

• Start with M for most work
• Use S or XS for quick, focused tasks
• Scale up to L or XL for large builds, heavy indexing, or memory-intensive work

How environments work in Cloud

When you create a task in Cloud:

1. You select an environment (base or custom) and size
2. Cosine provisions a workspace with that environment
3. The task runs in that workspace
4. Changes are pushed to your repository

Workspaces are ephemeral — created when the task starts and destroyed when it ends. Only your code changes (commits and branches) are persisted.

See Also

• Desktop Environments — Environment management in Desktop
• Cloud Overview — How Cloud fits with the rest of Cosine
• Quickstart — Fastest path to your first task in Cloud