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. For the day-to-day flows that use these connections, see Sync to IBM i, Import IBM i Sources, and Generate IBM i 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.
• 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 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 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.

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.
• 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):

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 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