About cloud environments
Cloud environments are Augment hosted compute for Cosmos. The environment consists of the base image, selected repositories, environment variables, and additional configuration that enable your agents to complete tasks. Each session starts from a fresh isolated snapshot of your environment and will automatically scale its resources for the workload. Cloud environments are used for both interactive and automation sessions. In most organizations, environments are configured for reuse by the entire team rather than a custom environment for each user.Putting sensitive information or credentials into an environment through environment variables or files will allow any user or agent that starts a session with the environment to access those secrets.
Configuration
Name
Each environment must have a unique name across your entire organization. Environments are frequently named for the teams or projects they are built for: API Backend, Mobile Development, Analytics.Base image
The base image is the Docker image that the environment is built from. You can choose from the curated list of images or choose any image from a public Docker registry with the required dependencies (bash and git). You can install additional packages after the environment is created.
Cosmos base images
| Name | Details |
|---|---|
| Cosmos Default | Ubuntu 24.04 with Python 3.12 and Node.js 22. Good general-purpose choice. |
| TypeScript 6.0 | Debian 12 dev container with TypeScript 6.0 |
| Python 3.12 | Official Python 3.12 dev environment |
| Go 1.24 | Official Go 1.24 dev environment |
| PHP 8.4 | Official PHP 8.4 dev environment |
| Ruby 3.4 | Official Ruby 3.4 dev environment |
| Rust 1.95 | Official Rust 1.95 dev environment |
docker.io/library/ubuntu:24.04. Your selected image must have the following dependencies installed: bash and git.
Repositories
If you’ve connected your GitHub organization to Cosmos, you will be able to select which repositories are cloned to your environment automatically. You may select multiple repositories for a single environment and Cosmos will be able to work across them. If you have not installed the GitHub App or are using another source control platform, you can clone the repositories manually after the environment is created. Selected repositories are cloned into/workspace/{org}/{repo} automatically. You can add any additional git repositories to the /workspace directory that are not accessible with the GitHub App integration.
Environment variables
Do not store sensitive values in environment variables, use Secrets instead. Environment variables may appear in internal logs or session output, secrets are redacted automatically.
- Names must start with a letter or underscore, and only contain letters, numbers, or underscores.
- Name cannot start with
AUGMENT_. - Names must be unique within the environment.
Hooks
You can utilize lifecycle hooks to run automatically to keep your environment and repositories up-to-date. All hook scripts are located in/hooks. You can customize the behavior of each of the hooks by editing the hook script. The available hooks are:
| Hook | File | Description |
|---|---|---|
| Start | on_startup.sh | Runs when the environment first starts |
| Refresh | on_refresh.sh | Manually run, or runs every 12 hours when enabled |
Sharing
Sharing an environment allows an entire team to utilize the best practices, tools, and configuration for a consistent agent experience. Environments utilize the object-level access controls (OLAC) that all other resources use in Cosmos.Networking
All cloud environments have egress (outbound) network access only. Network access from the environment is separate from the network access configured for a Session. Tools likecurl and other CLIs are able to connect to publicly accessible network resources from within the environment. Ingress traffic to the environment, from a web browser for example, is not enabled.
Running Tailscale
You can enable external access to the environment through services such as Tailscale, though you will need to configure it with userspace networking instead of the default networking configuration. After you’ve installedtailscaled in the environment, start it with the following command:
on_startup.sh hook to have Tailscale launch automatically with each session.
Then start your app with the necessary proxy variables set, for example:
Additional dependencies and configuration
After an environment is created, you can use the built-in terminal to run commands and install additional dependencies to finish the configuration for your projects. After you have run any additional commands (e.g.,pnpm install), select Update environment to save the current environment state.
Updating an environment
You can update an environment in a number of ways:- Manually through the web terminal and environment form
- By using an existing session’s environment as the new base environment
- Asking the Cosmos Advisor to update the environment for you
Manual updates
You can update an environment configuration such as Environment Variables, synced Repositories, or other metadata by going to the environment in Cosmos web and making changes. You can also selectTerminal to launch an interactive terminal to change configuration on the filesystem, such as installed packages.
After you make changes either in the web form or terminal, you must select Update environment to persist the changes.
From existing session
You may want to use an existing session as the base of your environment. This is particularly useful when you have an agent make changes to the environment for you, such as when you are first configuring an environment for a project. To save an environment from a session:- Go to the session that will be the source of your environment
- Open the session sidebar
- Under Environment, select the kebab menu
- Select Update environment from session. If you do not have the proper permissions to update an environment, you can Create a new environment instead.
Using Cosmos Advisor
You can use Cosmos Advisor to update an environment for you. Select the Advisor expert and use natural language to describe the changes you want to make.Refreshing an environment
Environments can be updated automatically to retrieve the latest changes to your codebase, keep your dependencies up-to-date, or any other maintenance task you need to run. Each environment has a built-in refreshbash script at /hooks/on_refresh.sh that you can update. Refreshing your environment will allow your agents to work more effectively.
By default the refresh script includes automatically fetching the latest changes to your git repositories located in /workspace, even if they were manually added by you. Update the script to run other commands, like pnpm install, to keep them up-to-date with your repos.
If enabled in the environment configuration, the refresh script will run every 12 hours. You can also manually run the refresh script from the Cosmos web UI.