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 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 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 before running tasks
• IBM i Source Import — Designate this repository as the target for the Import IBM i Sources and Generate IBM i Build Rules tools. Only one repository per environment can have this enabled.

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

Proxy URL vs. QA URL

Use Proxy URL when CoderFlow should forward task app traffic to an already-running application server instead of starting one inside the task container. In proxy mode, task app links go through CoderFlow's task proxy, which forwards requests to the target URL, adds forwarded headers, handles configured basic auth and proxy headers, and injects the feedback widget into HTML responses.

Use QA URL for QA Mode launch links. QA URLs point to the externally reachable application address that testers should open through the QA proxy. They support {{origin}}, {{host}}, {{hostname}}, and {{protocol}} placeholders, plus port-specific QA URL overrides. QA Mode uses these URLs to expose the app through /qa/... routes with widget injection; it does not use the task app proxy target as a fallback.

Agent Instructions

The Agent Instructions tab manages the environment's AGENTS.md file. This is the durable, project-specific guidance mounted into task, interactive, and deployment containers at /coder-setup/{environment}/AGENTS.md.

Use AGENTS.md for standing instructions that every agent should know before working in the environment:

• Project structure and architecture
• Build, test, and verification commands
• Coding conventions and review expectations
• Repository-specific safety rules
• Domain-specific knowledge agents need

The tab also includes Standard Instructions toggles. These are predefined instruction blocks, such as output requirements or IBM i verification guidance, that CoderFlow appends at task startup when enabled. Keep custom instructions focused on your project; use the toggles for CoderFlow-managed conventions that should remain consistent across environments.

Agents with permission to update environment instructions can also use the Environment Instructions skill during a task to view or propose updates to AGENTS.md. Use the separate Memory tab for accumulated project notes that should be loaded as memory; AGENTS.md is best for stable operating rules.

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:

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

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

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

To expose a secret as an environment variable:

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

See Docker Build 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 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:

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 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 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), 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 / deploy credentials setting controls how member sync and UI deploy authenticate:

  • Prompt (default for new connections) — You are prompted for a user profile and password each time you sync or deploy. No SSH key or SSH feature is required.
  • Connection — Sync and deploy use the SSH user and key configured on the connection. Requires the SSH feature to be enabled.

  See IBM i Sync for usage details.

• Profound UI htdocs Files — Deploys approved task changes under htdocs/profoundui/ to the configured IBM i htdocs directory, preserving the path below htdocs. Requires PUI htdocs Path (for example /www/myinstance/htdocs) and the Tasks availability scope. Deploy uses the same Sync / deploy credentials mode as source member sync on that connection.

• Agentic Display Files — Enables task-scoped Profound UI EJS screen overlays for RPG Open Access applications. Requests for /profoundui/userdata/ui/* can be served from files inside the task workspace instead of the IBM i IFS, so developers can preview EJS templates, CSS, and JavaScript without changing the shared system. This feature also enables Profound UI htdocs deploy and requires PUI htdocs Path and the Tasks availability scope.

• 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/htdocs deploy 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 RSA 4096-bit keypair on the server (ssh-keygen -t rsa -b 4096). 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	Profound UI htdocs Files	(none)
IBM i	Agentic Display Files	ejs-screen-designer
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.

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

Test definitions are stored in tests.json in the environment directory. See Test Definitions for the file format, parameters, and CLI behavior.

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.

Profiles are stored as paired JSON and shell files under deployment-profiles/ in the environment directory. See Deployment Profiles for authoring details.

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:

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, Bob Shell, Grok Build) to the latest version or after updating core dependencies. Use the Build Base Image option in Settings → Environments → Actions, or from the CLI:

coder-server build base

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