---
sidebar_position: 2
---
# IBM i Connections

CoderFlow talks to IBM i systems through **external connections** configured per environment. Each connection enables one or more features — SQL, Build, SSH, Sync, Profound UI htdocs deploy, Agentic Display Files, or Interactive Sessions — and each feature has its own requirements on the IBM i side.

This page covers what those requirements are: what services must be running on the IBM i system, what authority the user profile needs, and how the Profound UI features are configured. For the field-by-field reference of the connection form itself, see [Environments → Connections](/admin/environments#connections). For the day-to-day flows that use these connections, see [Sync to IBM i](/ibmi/sync-to-library), [Import IBM i Sources](/ibmi/import-sources), and [Generate IBM i Build Rules](/ibmi/build-rules).

## Connection Basics

An IBM i connection is created from the environment configuration page. Each connection has:

- **Host** — the IBM i system's fully qualified domain name (must match the FQDN regex; raw IPs are not accepted).
- **User** — the IBM i user profile CoderFlow authenticates as. Required when SQL, SSH, Build, Interactive Sessions, or Connection-mode sync/deploy is enabled.
- **Password** — required when SQL or Interactive Sessions is enabled (used by the RAS-backed `sql` skill and Profound UI authentication).
- **SSH private key** — required when SSH or Build is enabled, or when sync/deploy is set to **Connection** credentials mode.
- **Features** — the set of capabilities that should be activated. Each feature has its own IBM i-side prerequisites, listed below.
- **Available For** — `tasks`, `deploy`, or both. Most connections use Tasks.

A single environment can have at most one IBM i connection with the **Build**, **Sync**, or **Interactive Sessions** feature per scope. SQL-only and SSH-only connections can be combined freely.

## SQL — Database Access via DB2

The **SQL** feature lets agents run queries against DB2 from inside the task container, using the `sql` skill.

**On the IBM i system:**

- **Profound Logic Remote Access Server (RAS)** must be installed and running. RAS is the network service the `sql` skill connects to — it offers materially better performance than direct ODBC/JDBC over network distances. Installation and configuration are covered in the [Profound Logic RAS documentation](https://profoundlogicsupport.atlassian.net/wiki/x/GgAoYw).
- The IBM i user profile needs database authority appropriate to what your agents will read or write — typically `*USE` on the relevant schemas and `*OBJOPR`/`*READ` on tables the agents are expected to query.
- The user's password is required on the connection. SQL is one of the two features (the other is Interactive Sessions) that does not work with SSH-key-only authentication.

**On the CoderFlow side:** saving the connection auto-imports the `sql` skill for tasks in this environment, so agents can call it without manual skill assignment.

## Build — codermake Compilation

The **Build** feature is what enables `codermake` inside the task container, lets agents compile RPG/COBOL/CL/DDS programs, and triggers per-task library creation.

**On the IBM i system:**

- The **SSH daemon** must be running and reachable from the CoderFlow server. Build is SSH-key-only — there is no password fallback.
- The user profile needs:
  - Authority to create libraries (`CRTLIB`) — task libraries are created on demand.
  - Authority to compile into the resulting library (typically through the user's normal `*ALLOBJ` or per-object grants on the source members).
  - QShell (`/usr/bin/qsh`) accessible. CoderFlow runs DB2 and `system` commands via QShell.
- The user's home directory and `.ssh` directory must exist on the IFS for `authorized_keys` to be written. The connection form's **How to set up IBM i user profile** helper generates `CRTDIR /home/<user>` and `CHGOWN`/`chmod` commands to bootstrap this.
- The job description (JOBD) or the user's initial program should set up an appropriate library list. CoderFlow does not modify the IBM i library list during compilation — agents inherit whatever the user profile is configured for, and `codermake` adds the per-task build library on top.

**On the CoderFlow side:** the connection requires three additional fields when Build is enabled — **Build Repo** (which environment repository `codermake` runs in), optional **Build Directory** (a subdirectory inside that repo), and **Build Library Name Prefix** (1–5 characters that prefix the per-task library name, e.g. `AITSK`). See [Task Libraries](/ibmi/task-libraries) for how the library is created and cleaned up.

## SSH — Shell Access

The **SSH** feature gives agents the ability to run CL commands and arbitrary shell commands on the IBM i system through the `ibmi-clcmd` skill. It also acts as the SSH-key home for connections that use Connection-mode sync/deploy.

**On the IBM i system:**

- The SSH daemon must be running.
- The user profile must have a home directory on the IFS with `.ssh/authorized_keys` writable. The CoderFlow public key is appended via `ssh-copy-id`-style logic when you use the **Install Public Key on Remote** button — that operation requires the remote user's password once but does not store it.
- For CL command execution, the user needs `*USE` on the commands the agent will run. CL commands are executed through QShell (`system "..."`) so the user's QShell environment must be functional.

## Sync — Source Member Sync

The **Sync** feature surfaces the [Sync to IBM i](/ibmi/sync-to-library) flow. It writes changed source files from the task workspace into source members on a target IBM i library after task approval.

**On the IBM i system:**

- The SSH daemon must be running. Sync runs entirely over SSH — both for the script that creates libraries and for the `Rfile -Qw` writes that put member content in place.
- The user profile (whether the connection's profile or the prompted one) needs:
  - `CRTLIB` if the target library doesn't already exist, or `*USE` and `*ADD` on the existing library.
  - `CRTSRCPF` and `*OBJOPR`/`*ADD` on source physical files.
  - `ADDPFM`, `CHGPFM`, and member-write authority for content updates.
- QShell must be functional — `Rfile` and the `system` CL wrapper both run inside QShell.

**Sync / deploy credentials** is configured per connection:
- **Prompt** (default) — the operator enters a user profile and password each time. The operator's IBM i authority is what's used. No SSH key is required on the connection for sync alone.
- **Connection** — the connection's SSH user/key is used. The **SSH** feature must also be enabled, since Connection-mode sync reuses that SSH configuration.

## Profound UI htdocs Files and Agentic Display Files

These two features both deploy files to the **Profound UI htdocs IFS path** on the IBM i system. They differ in what additional capabilities they enable inside the task container:

- **Profound UI htdocs Files** — pure deploy. Files in `htdocs/profoundui/` in the task workspace are pushed to the configured `pui_htdocs_path` on approval.
- **Agentic Display Files** — adds the `ejs-screen-designer` skill so agents can create and edit EJS screen overlays for RPG Open Access programs, and routes `/profoundui/userdata/ui/*` requests to files inside the task workspace (instead of the shared IFS) when the application server proxy is in use. This lets developers preview EJS templates, CSS, and JavaScript changes without touching the production IFS until the task is approved.

**On the IBM i system:**

- Profound UI must be installed at the path specified by **PUI htdocs Path** (e.g., `/www/myinstance/htdocs`). The path must be absolute and must not contain `.` or `..` segments.
- The SSH user (whether prompted or the connection's user) needs write authority on the target IFS path. CoderFlow's deploy script copies files via `scp` and creates intermediate directories as needed.
- Both features require the **Tasks** availability scope; deploy doesn't make sense without a task to deploy from.

These features share the **Sync / deploy credentials** mode with source member sync. If the same connection has both Sync and a deploy feature, they use the same credentials policy.

## Interactive Sessions

The **Interactive Sessions** feature lets agents drive 5250 terminal and Rich Display sessions through Profound UI for end-to-end testing of running applications.

**On the IBM i system:**

- Profound UI must be installed and reachable at the URL configured in the connection's **PUI Base URL**. The base URL's hostname must match the connection's host field — connections are validated to enforce this.
- A typical setup uses three URLs:
  - **PUI Base URL** — for example `https://myibmi.mycompany.com:8080`. Where Profound UI listens.
  - **PUI Render Path** — defaults to `/profoundui/genie`. Where rendered screens are served from.
  - **PUI Launch Path** — defaults to `/profoundui/auth/genie`. Where new sessions are launched (used for the auto-generated launch URL on the application server).
- The user profile must call `PUISETENV` from its initial program (or have the JOBD set it up) so that the Profound UI Genie environment is initialized when the session starts. The connection helper dialog flags this requirement.
- The user's password is required on the connection — Profound UI uses HTTP basic auth, and CoderFlow forwards the connection's user/password automatically.

**Inside the task container:** when Interactive Sessions is enabled, the application server's proxy is automatically pointed at the Profound UI base URL, basic auth is configured from the connection, an `X-Agentic-Task-Lib` header is added carrying `${IBMI_BUILD_LIBRARY}` (so Profound UI can use the per-task build library), and a launch URL named `Genie (<connection-name>)` is added to the application server's launch URLs.

The `ibmi-interactive-session` skill is auto-imported, giving agents the API they need to navigate screens, enter data, press function keys, and capture output for [task visualizations](/testing/task-visualizations).

### Rich Display Rendering

When Interactive Sessions is in use, Profound UI renders the IBM i job's display files — including any DDS, RDF, or EJS Rich Display Files in the task's build library — as HTML in the Genie web UI. CoderFlow records the resulting screens for the task's visualizations.

For Rich Display **authoring**, two paths are relevant:
- **Sync to IBM i with `.json` Rich Displays**: when source-member sync runs, EJS-template and traditional RDF `.json` files are converted to DDS and synced as `DSPF` members. See [Rich Display Files](/ibmi/sync-to-library#rich-display-files-json).
- **Agentic Display Files**: enables the `ejs-screen-designer` skill so agents can create EJS overlays for Open Access RPG, and serves them from the task workspace before they're deployed. The companion htdocs deploy step pushes them to the IFS on approval.

## SSH Key Management

For SSH-using features, the connection form provides three options for the keypair:

- **Import from file** — paste or upload an existing private/public key.
- **Generate Keypair** — server-side generation of a new RSA 4096-bit keypair (`ssh-keygen -t rsa -b 4096`). Both fields populate automatically.
- **Install Public Key on Remote** — appends the public key to the remote user's `authorized_keys`. Requires the remote user's password once for the install operation only — it is not stored. The install is idempotent (uses `grep -qxF`), so repeating it for an already-installed key is a no-op.

The **Test SSH** button validates connectivity using the values currently in the form (not the last-saved values), so you can adjust a field and retest without saving in between.

## IBM i User Profile Setup Helper

The connection form includes a **How to set up IBM i user profile** dialog that generates copy-paste-ready CL commands for bootstrapping a new service-account profile. The commands are tailored to the values you've entered in the form (user name, password if you've typed one):

```cl
CRTUSRPRF USRPRF(<USER>) PASSWORD(<password>) USRCLS(*USER) INLMNU(*SIGNOFF) LMTCPB(*YES) TEXT('CoderFlow service account') SPCAUT(*NONE) JOBD(JOB_DESCRIPTION)
CRTDIR DIR('/home/<user>')
CHGOWN OBJ('/home/<user>') NEWOWN(<USER>)
QSH CMD('chmod 755 /home/<user>')
```

Each command can be copied individually. Manual setup steps not covered by the helper:
- Configure the user's JOBD (or initial program) to set up the appropriate library list for the agents' work.
- For Interactive Sessions, ensure `PUISETENV` is called as part of the user's initial program so the Profound UI environment is ready when the session starts.
- SSH public key installation is handled by the **Install Public Key on Remote** button, not by the CL helper.

## Skills Auto-Import

Saving an IBM i connection automatically imports and assigns the relevant skills to the environment, so agents have the tools they need without manual skill management:

| Feature | Skill Auto-Imported |
|---------|---------------------|
| SQL | `sql` |
| Build | `codermake` |
| SSH | `ibmi-clcmd` |
| Interactive Sessions | `ibmi-interactive-session` |
| Agentic Display Files | `ejs-screen-designer` |
| Profound UI htdocs Files | *(none — deploy-only)* |
| Sync | *(none — server-side flow only)* |

Skills are only added, never removed. Deleting a connection does not unassign its skills — that's a manual cleanup step in the environment skills configuration.

## Restrictions and Common Pitfalls

- An environment can have **at most one** IBM i connection with **Build**, **Sync**, or **Interactive Sessions** per availability scope. SQL-only and SSH-only connections can be combined freely. The form rejects a save that would create a second build/sync/interactive connection in the same scope.
- **Interactive Sessions** requires the **Tasks** scope. It does not make sense for `deploy` containers, which have no agent.
- **Connection-mode sync/deploy** requires the **SSH** feature (since it reuses the connection's SSH key). Validation rejects a save without it.
- The **PUI Base URL** hostname must match the connection's **Host**. A mismatch is rejected at save time — for example, you can't point a connection at `myibmi.mycompany.com` and put the PUI base URL at `pui.example.com`.
- The **Build Library Name Prefix** must be 1–5 characters, first character `A`–`Z`, `@`, `#`, or `$`; remaining characters letters, digits, `@`, `#`, `$`, `_`, or `.`. Anything else is rejected. See [Task Libraries](/ibmi/task-libraries) for how the prefix is used.

## Where Each Feature's Source Lives

For internal reference and for finding behavior the docs don't cover yet:

| Concern | File |
|---------|------|
| Connection types, features, validation | `packages/server/lib/external-connections.js` |
| Per-task library creation and cleanup | `packages/base-image/entrypoint.sh` (`setup_ibmi_build_library`) |
| Source-member sync script | `packages/server/scripts/sync_to_ibmi.sh` |
| Source-member sync orchestration | `packages/server/lib/ibmi-sync.js` |
| Profound UI htdocs deploy script | `packages/server/scripts/deploy_pui_ui.sh` |
| Profound UI htdocs deploy orchestration | `packages/server/lib/pui-deploy.js` |
| Rich Display JSON → DDS conversion | `packages/server/lib/ibmi-richdisplay.js` |
