Skip to content
Cosine

Locations and environments

A location is where Cosine runs while working on your code. A location can be your current local workspace, a separate local worktree, or a remote workspace managed by Cosine.

An environment is the runtime used inside a remote location. It defines the operating system, tools, dependencies, secrets, and resource size available to the agent.

This is different from a surface. A surface is where you control Cosine from. A location is where the work runs.

Locations

Section titled “Locations”

Cosine supports three main locations.

Local

Section titled “Local”

Local runs directly in your current workspace on your machine.

  • Use when: You want fast iteration and immediate access to your existing files, dependencies, terminals, local services, browser, and MCP servers
  • Tradeoff: Cosine works in the same checkout you are using, so changes appear directly in your current workspace

Worktree

Section titled “Worktree”

Worktree runs locally in a separate Git worktree.

  • Use when: You want local execution with more isolation from your current checkout
  • Tradeoff: It requires a Git repository and creates a separate branch/directory for the work

Remote

Section titled “Remote”

Remote runs in a cloud-hosted workspace outside your local machine.

  • Use when: You want Cosine to work without relying on your machine, need more resources, or want a consistent team runtime
  • Tradeoff: The workspace is usually ephemeral; code changes, commits, branches, and review artifacts persist, but the remote workspace itself is cleaned up

Remote environments

Section titled “Remote environments”

When a task runs remotely, you choose an environment. The environment controls what is available inside that remote workspace.

An environment can include:

  • operating system and base tools
  • language runtimes and package managers
  • project dependencies
  • browser, desktop, or editor capabilities
  • secrets and environment variables
  • resource size

Base and custom environments

Section titled “Base and custom environments”

Cosine provides a default Ubuntu environment for most remote work.

You can also create custom environments when a project needs specific tools, language versions, system packages, services, browser or desktop access, or secrets. Custom environments make tasks more repeatable because dependencies are prepared before the agent starts working.

How this differs by surface

Section titled “How this differs by surface”
  • Cloud runs tasks remotely, so you choose a remote environment and size when creating a task
  • Desktop can run locally, in a local worktree, or remotely with an environment
  • CLI normally runs in your local workspace, with workspace modes such as direct filesystem access or worktree-style isolation
  • VS Code keeps Cosine close to your editor context and local workspace

Environment configuration

Section titled “Environment configuration”

Environment configuration can live in several places:

  • Repository config — Project files such as .cosine/Dockerfile, named environment Dockerfiles, and .cosine/defaults.json
  • Cloud project settings — Environment selection, sizes, secrets, and build controls in the dashboard
  • Desktop settings — Local, worktree, and remote locations, including shared custom environments
  • Enterprise deployments — Private cloud, VPC, or fully air-gapped infrastructure
Section titled “Related pages”