# Environments

An environment defines where agents work—the Docker image, repositories, tools, and configuration they need to complete tasks. Administrators manage environments through the Web UI.

## Configuration Storage

All environment configuration is stored in your organization's coder setup repository—a git repository that defines your CoderFlow installation. This includes Dockerfiles, setup scripts, agent instructions, templates, and environment settings.

The Web UI provides a complete interface for managing this configuration:

- **Save** — Write changes to disk without committing
- **Discard** — Revert uncommitted changes
- **Commit & Push** — Commit changes to git and push to the remote repository

This workflow lets you experiment with configuration changes before committing them. The repository status shows uncommitted changes, and you can pull updates from the remote to stay in sync with your team.

## Environment Configuration

Navigate to **Environments** in the Web UI to create and configure environments. Each environment has the following tabs:

### Overview

Basic environment settings:
- **Description** — What this environment is for
- **Default Agent** — AI agent to use for tasks
- **Docker Image** — Container image name
- **Timezone** — Timezone for the environment
- **Skills** — Skills assigned to this environment
- **README** — Documentation displayed to users

### Repositories

Git repositories cloned into the environment. To add a repository, click **Add Repository** and choose one of:

- **With Git Provider** — Select a [Git Provider](admin/git-providers.md) from the dropdown, then choose a repository from the list of repos the provider can access. Authentication is automatic for all Git operations (clone, fetch, push) in builds, tasks, and deployments.
- **Manual Entry** — Enter a repository URL directly without selecting a provider. Use this for public repositories or when using [PAT secrets](#using-secrets-as-git-pat) for authentication.

Repository settings:
- **Branch** — Default branch to check out
- **Allow Branch Selection** — Let users choose branches when creating tasks
- **Path** — Where to clone the repository in the container
- **Credential Mode** — How Git operations authenticate with the remote provider (Git Provider repos only):
  - **App Credentials** — Uses the provider's application identity (default)
  - **User Credentials** — Uses each user's personal Git account via OAuth; requires users to [connect their Git account](admin/git-providers.md#connecting-your-git-account) before running tasks

### Application Server

Configuration for running and testing applications:
- **Start Command** — How to launch the application server
- **Proxy URL** — URL for proxying requests to the application
- **QA URL** — URL template for testing (supports placeholders)
- **Authentication** — Credentials for accessing the application
- **Ports** — Ports to expose from the container
- **Launch URLs** — Quick links for testing the application

### Agent Instructions

The AGENTS.md file that guides AI agents working in this environment. This markdown file describes:
- Project structure and architecture
- Build and test commands
- Coding conventions and patterns
- Domain-specific knowledge agents need

### Skills

Skills are reusable prompt-based actions that agents can invoke during tasks. In the **Overview** tab, use **Manage Skills** to assign skills to the environment. Assigned skills are injected into every task launched in this environment, so agents have them available immediately.

If you need different skills for different projects, create separate environments or update the assigned skill set before launching new tasks.

### Files

Configuration files that define the environment:
- **Dockerfile** — How the Docker image is built
- **setup.sh** — Initialization script run when containers start
- **cleanup.sh** — Cleanup script run when tasks complete

### Secrets

Secrets store sensitive values like API keys, credentials, and certificates for use in builds, tasks, and deployments. They are also used to define non-sensitive environment values like external service URLs, ports, and so on.

**Defining Secrets**

Navigate to the environment's **Secrets** tab and click **Add Secret**:

- **Name** — Identifier for the secret (letters, numbers, underscores)
- **Type** — Value (literal string) or File (path to a file on the host)
- **Available For** — Where the secret can be used: Build, Tasks, Deploy
- **Expose As** — How to expose the secret in Tasks/Deploy contexts: environment variable or file mount
- **Target** — Variable name (for env var) or container path (for file mount)

**Secret Types**

- **Value** — Stores literal strings such as API keys, passwords, or tokens. Can be exposed as an environment variable.
- **File** — References a file on the host system such as SSH keys or certificates. Can be mounted read-only in containers.

**Using Secrets in Tasks**

Secrets with **Tasks** availability are injected when task containers start:

- **Expose as environment variable** — The secret value becomes available as the specified variable name
- **Expose as file** — The file is mounted read-only at the specified container path

**Using Secrets in Builds**

Secrets with **Build** availability are passed to Docker BuildKit during image builds. Access them in your Dockerfile using `--mount=type=secret`:

```dockerfile
RUN --mount=type=secret,id=my_secret cat /run/secrets/my_secret
```

For example, to use an `.npmrc` file during build:

```dockerfile
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm install
```

To expose a secret as an environment variable:

```dockerfile
RUN --mount=type=secret,id=api_key,env=API_KEY ./configure.sh
```

See [Docker Build Secrets](https://docs.docker.com/build/building/secrets/) for more details.

**Using Secrets in Deployments**

Secrets with **Deploy** availability are injected when deployment scripts run:

- **Expose as environment variable** — The secret value becomes available as the specified variable name in the deployment script
- **Expose as file** — The file is mounted read-only at the specified container path during deployment

This is useful for storing deployment credentials, SSH keys for remote servers, API tokens for deployment services, or configuration files specific to deployment targets (Base, QA, Production).

**Using Secrets as Git PAT**

A secret can provide Git authentication for HTTPS repositories. When adding a secret, check **Use as Git PAT** and specify a **Git Host** (e.g., `github.com`) to use the secret as a Personal Access Token for Git operations. The PAT applies to any repository under [Repositories](#repositories) that matches the hostname.

PAT secrets can be either **Value** type (token entered directly) or **File** type (token read from a file on the host). Select **Available For** contexts as needed—Build, Tasks, or Deploy. PAT secrets do not require "Expose as" configuration.

In **builds**, PAT credentials are available as the `git-credentials` build secret. Mount it to the standard Git credentials location:

```dockerfile
RUN --mount=type=secret,id=git-credentials,target=/root/.git-credentials \
    git clone https://github.com/myorg/private-repo.git
```

In **task and deployment containers**, the PAT is automatically configured in the Git credential store.

**Note:** PAT secrets are ignored for repositories that have a [Git Provider](admin/git-providers.md) configured.

### Connections

Connections define external servers that containers can access during tasks and deployments. Instead of manually configuring SSH keys, database credentials, and environment variables through secrets and setup scripts, connections handle this automatically—you declare a connection once, and CoderFlow injects the appropriate configuration into every container that needs it.

Click **Add Connection** to create a new connection. Each connection has a **Name**, optional **Description**, **Type**, and **Available For** scope.

**Connection Types**

- **SQL Server** — Connects to a Microsoft SQL Server database. Requires host, database, user, and password. An option to verify the DB server's TLS certificate is enabled by default. Containers receive a pre-configured database connection that agents use through the `sql` skill.

- **IBM i** — Connects to an IBM i system. IBM i connections are feature-based—you select which capabilities to enable, and CoderFlow configures only what's needed. Features are independent and can be selected in any combination. See [IBM i Features](#ibm-i-features) below.

- **SSH** — Connects to a generic SSH server. Requires host, user, and an SSH private key. Containers receive a configured SSH key and host entry so agents or scripts can connect using `ssh <connection-name>`.

**Available For**

Controls which container contexts receive the connection's configuration:

- **Tasks** — Task containers, interactive test containers, and standalone test containers
- **Deploy** — Deployment script containers

At least one scope must be selected. Most connections use Tasks. Add Deploy when deployment scripts need access to the same external server.

**IBM i Features**

When creating an IBM i connection, select one or more features:

- **SQL** — Database access via DB2. Agents use the `sql` skill to execute queries, inspect schemas, and verify data. Connectivity is provided by [Profound Logic Remote Access Server (RAS)](https://profoundlogicsupport.atlassian.net/wiki/x/GgAoYw), which must be installed on the IBM i system. Requires a password.
- **Build** — IBM i program compilation using `codermake`. Each task gets its own isolated build library, created automatically when tasks start and cleaned up when they end. Requires an SSH key. Additional fields appear for **Build Repo** (which environment repository `codermake` runs in), optional **Build Directory** (subdirectory within the repo), and **Build Library Name Prefix** (1–5 character prefix for task library names, e.g., `AITSK`).
- **Sync** — Sync approved task changes to an IBM i library. When enabled, the approval dialog offers a **Sync to IBM i** checkbox, and approved tasks show a **Sync to IBM i** button for syncing after the fact. Source members are created from changed files and written to the specified library. A **Sync credentials** setting controls how the sync authenticates:
  - **Prompt** (default for new connections) — You are prompted for a user profile and password each time you sync. No SSH key or SSH feature is required.
  - **Connection** — Sync uses the SSH user and key configured on the connection. Requires the SSH feature to be enabled.

  See [IBM i Sync](tasks/approval-and-deployment.md#ibm-i-sync) for usage details.
- **SSH** — SSH shell access to the IBM i system. Agents use the `ibmi-clcmd` skill to run CL commands remotely. Requires an SSH key.
- **Interactive Sessions** — Agent-driven interactive testing through Profound UI. Agents can operate 5250 terminal and Rich Display sessions, with recordings visible in task visualizations. Requires a password. Additional fields appear for **PUI Base URL**, **PUI Render Path**, and **PUI Launch Path**. This feature requires the Tasks availability scope.

When multiple features are selected on the same connection, they share configuration where appropriate—for example, Build uses the SSH key from the SSH feature when both are enabled.

**SSH Key Management**

Connections that require SSH access (IBM i with SSH or Build features, Sync in "Connection" mode, and generic SSH connections) need a keypair. The connection form provides several options:

- **Import from file** — Upload an existing private or public key file from your local machine
- **Generate Keypair** — Generate a new Ed25519 keypair on the server. Both key fields are populated automatically.
- **Install Public Key on Remote** — After saving a connection with a keypair, this button automates adding the public key to the remote host's `authorized_keys`. Enter the remote user's password (used only for this operation, not saved), and CoderFlow runs `ssh-copy-id` to install the key.

**Testing Connections**

Use the test buttons in the edit dialog to verify connectivity:

- **Test SQL** — Attempts a database connection using the current form values
- **Test SSH** — Attempts an SSH connection using the current form values

Tests use the values visible in the form, not the last-saved values, so you can change a field and test immediately without saving first.

**Skills Auto-Import**

When you save a connection, CoderFlow automatically imports and assigns the skills agents need:

| Connection Type | Feature | Skill |
|---|---|---|
| SQL Server | — | `sql` |
| IBM i | SQL | `sql` |
| IBM i | Build | `codermake` |
| IBM i | SSH | `ibmi-clcmd` |
| IBM i | Interactive Sessions | `ibmi-interactive-session` |
| SSH | — | *(none)* |

Skills are only added, never removed—deleting a connection does not remove its associated skills.

**IBM i User Profile Setup**

IBM i connections require a properly configured user profile on the IBM i system. Click **How to set up IBM i user profile** in the connection form to see the CL commands for creating and configuring the profile. Each command can be copied individually. Additional manual setup includes configuring the user's JOBD or initial program for the appropriate library list, and ensuring PUISETENV is called for interactive sessions.

**Restrictions**

- An environment can have at most one IBM i connection with the Build, Sync, or Interactive Sessions feature per availability scope. Multiple IBM i connections with only SQL and/or SSH features are allowed.
- The Interactive Sessions feature requires the Tasks availability scope.

### Build

Building and scheduling:
- **Schedule** — Automatic rebuild interval (e.g., nightly)
- **Build History** — Previous builds with status and duration
- **Build Now** — Trigger an immediate rebuild

For build-time secrets (SSH keys, tokens), see [Secrets / Env Vars](#secrets).

Rebuild the environment after changing the Dockerfile, setup scripts, or dependencies.

### Tests

Test commands available in the Testing menu:
- Define commands agents can run to verify their changes
- Configure expected outputs or assertions

### Templates

Task templates for this environment:
- Reusable task definitions with parameters
- See **Templates** section for details

### Deployment Profiles

Deployment Profiles provide built-in CI/CD capabilities for deploying code to different targets.

Each profile defines:
- **Target** — Where code deploys (Base, QA, Production, etc.)
- **Deployment script** — Commands to run (e.g., setting environment variables, running build tools)
- **Credentials** — Separate authentication for each target

Deployments aren't just for production—they're part of the regular workflow. For example, with IBM i development, after code is approved and pushed to repositories, a deployment compiles the changes to the base environment. Additional profiles can then deploy to QA or production systems.

For IBM i environments, this includes setting the right library list and running `codermake` against the target system.

Deployments can be triggered from the Web UI.

## Creating Environments

To create a new environment:
1. Navigate to **Environments** in the Web UI
2. Click **New Environment**
3. Configure the basic settings
4. Add repositories and set up the Dockerfile
5. Build the environment

## Building Environments

After configuring an environment, build its Docker image from the Build tab. Click **Build Now** to trigger a build. The build history shows previous builds with their status and duration.

For automation or command-line workflows, you can also build from the server:

```bash
coder-server build <env-name>
```

For automated workflows, scheduled rebuilds can pull the latest code and rebuild the image at regular intervals.

### Base Image

All environments build on top of a shared base image. Rebuild the base image to update agent CLIs (Claude Code, Codex, Gemini) to the latest version or after updating core dependencies. Use the **Build Base Image** option in **Settings → Environments → Actions**, or from the CLI:

```bash
coder-server build base
```

After rebuilding the base image, rebuild any environments that depend on it.
