Right then. You've installed IBM Bob, added the Premium Package for i, connected to your IBM i, and asked BOB a perfectly reasonable question like "what columns are in the INGREDIENTS table?" BOB answers in about two seconds, gets it right, and then helpfully offers to write you an RPG program to maintain it.

So how did a chatty AI running on a laptop in my office here on the Costa Blanca (sea view, tea cooling nicely) know what's in a Db2 for i table on a Power server miles away?

The short answer is Mapepire. The longer answer is this lesson. Kettle on. Let's go.

By the end of this lesson you'll know:

  •  What Mapepire actually is (and how to say it)
  • Exactly where it sits between BOB and your IBM i
  • Why an AI tool like BOB needs something like it in the first place
  • How to install, start and check the Mapepire server
  • How to talk to Mapepire yourself from Node.js 24, the same way the tools do
  • How to keep it secure, and what to do when it throws a wobbly
Heads up: IBM documents a lot of this, but not everything. Where I'm quoting IBM's docs I'll say so. Where I'm joining the dots myself, I'll say that too. Anything marked [CHECK] is worth a quick sanity check on your own system.

1. What is Mapepire?

Mapepire (say it MAH-pup-ee, it's a South American pit viper, and with languages called Python, Cobra and Viper about, a venom-fast database connector clearly had to be a snake too) is IBM's open-source database access layer for Db2 for i. The project describes itself as "a cloud-friendly IBM i database access layer, built with simplicity and performance in-mind."

It has two halves:

  • The server (mapepire-server), which runs on your IBM i. It's a Java program (built for Java 8 and up) that uses the IBM Toolbox for Java (JTOpen) to talk to Db2 for i.
  • The clients, small libraries you use from your application. There are SDKs for Node.js (@ibm/mapepire-js), Python (mapepire-python), Java and .NET.

The clever bit is where the hard work happens. With ODBC or JDBC, the client driver does the heavy lifting: CCSID conversion, password levels, IBM i's own wire protocol. That means you have to install a driver on every PC, server and container that wants to talk to your database. Mapepire flips that around. The server on IBM i does the work, and the client just sends JSON requests ("run this SQL") and gets JSON responses back. The client hardly does anything at all, which is the whole idea.

Mapepire can run in two ways:

ModeHow it worksWho uses it
Single modeThe client opens an SSH channel, starts the Mapepire JVM with --single, and talks JSON over stdin/stdout. The JVM ends when you disconnect.Code for IBM i by default, and so BOB too (see below)
Server (daemon) modeOne long-running Mapepire server on the IBM i accepts secure WebSocket connections, by default on port 8076.The IBM i MCP Server, your own apps, and Code for IBM i if you turn on Connect to remote Mapepire server
ODBC is like posting every customer a full set of tools so they can build their own sandwich. Mapepire is a sandwich shop with one hatch. You shout your order through it, and a sandwich comes back out.

2. So where does BOB come into it?

This is the bit I want to get exactly right, so here's what IBM actually says.

The documented facts:

  •  IBM's Bob docs say the IBM Bob Premium Package for i requires an active connection to an IBM i system via Code for IBM i, and that Code for IBM i connects over SSH.
  • When you install the Premium Package for i, it automatically installs a set of open-source IBM i extensions, including Code for IBM i (halcyontechltd.code-for-ibmi, 3.0.10 or later) and Db2 for IBM i (halcyontechltd.vscode-db2i).
  • IBM lists "run CL commands, SQL statements, and PASE commands directly against a connected IBM i system" as a key feature of the Premium Package.
  • The Code for IBM i docs say that since version 3, Code for IBM i uses Mapepire to access Db2 for i and run queries. In the default single mode it uploads the jar to your home directory (~/.vscode/mapepire-server-X.Y.Z.jar) and starts it over the SSH connection.

Put those together and you get the chain: BOB → Code for IBM i → Mapepire → Db2 for i.

Proof from the real world: in November 2026, BOB users on the IBM Community and on BOB's GitHub issue tracker (issue #3922) reported connections failing with the error "Failed to start Mapepire SQL job". The cause turned out to be Code for IBM i 3.0.13 uploading one Mapepire jar version and then checking for another. The stack trace runs straight through Code for IBM i's runSQL inside BOB's extensions folder. You don't get much clearer evidence than that of BOB's SQL going through Code for IBM i and Mapepire.

There's a second route too: the IBM i MCP Server. IBM's Agentic AI on IBM i guide lists "IBM Bob + IBM i MCP Server" as one of the deployment options. It says BOB "can query your IBM i systems directly as part of its development context, looking up schema, checking system state." The IBM i MCP Server (IBM/ibmi-mcp-server) runs your YAML-defined SQL tools, and Mapepire is a prerequisite for it. IBM's guide puts it plainly: "results stream back through Mapepire."

So whichever way you wire BOB up, the database conversation ends up going through Mapepire.

Fun fact: BOB itself is a VS Code-based IDE, and that same GitHub issue shows BOB 2.3.0 running on Node.js 24.15.0 under the covers. So yes, it's Node.js 24 all the way down. My nodejs24 obsession is officially vindicated.

3. The architecture, in one picture

Why does BOB use IBM-i Mapepire 1

4. Why does an AI tool need Mapepire? (My reasoning)

IBM doesn't publish a page called "why BOB uses Mapepire", so this section is my reasoning, backed by what IBM says in its MCP Server and Agentic AI docs. I think it makes a lot of sense once you look at what BOB actually has to do.

4.1 BOB doesn't live on your IBM i

BOB runs on your Windows or Mac PC (those are the supported platforms in IBM's prerequisites). Your data lives on a Power server. Something has to bridge that gap, and it can't involve getting every developer to install and configure an ODBC driver and a DSN before BOB can say hello.

With Mapepire in single mode there's nothing database-related to install on the PC at all. Code for IBM i already has an SSH connection open, pushes the jar up, and starts it. As far as the PC is concerned, the only port involved is SSH on 22.

4.2 On IBM i, everything is SQL

This is the big one. IBM's own guide says it better than I can: "virtually everything about the system is queryable through SQL... if an AI agent can run SQL against IBM i, it can do almost anything."

Think about what BOB needs to understand before it can write decent code for you:

  • What tables and columns exist? QSYS2.SYSTABLES, QSYS2.SYSCOLUMNS
  • What objects are in a library? QSYS2.OBJECT_STATISTICS
  • Who's allowed to do what? QSYS2.OBJECT_PRIVILEGES
  • How's the system doing? QSYS2.SYSTEM_STATUS_INFO, QSYS2.ACTIVE_JOB_INFO
  • Run a CL command: Mapepire can do that too, either in the SQL job (cl) or, from server 2.5.0, in a dedicated remote command job (rccl)

One connection and one simple protocol gets BOB at the catalog, the IBM i services, CL commands and your actual data. That's a lot of context for not much plumbing.

4.3 AI chats are lots of small, fast questions

The IBM i MCP Server README lists why traditional ODBC and JDBC "don't align well" with AI workloads. AI agents need fast, lightweight connections (they fire off lots of short queries), modern JSON-based protocols (lovely for TypeScript and JavaScript tools, which is exactly what VS Code extensions are written in), and low-latency responses for interactive conversations.

Mapepire speaks JSON natively, so there's no translation layer between "the AI wants to know something" and "here's a result set".

4.4 It's portable

BOB runs on Windows and macOS, it can now be self-hosted on Red Hat OpenShift (IBM announced that on 30 September 2026), and MCP servers can run in containers or on the IBM i itself. A pure-JavaScript client with no native driver works the same in all of them. Try saying that about an ODBC driver inside an Alpine container. Actually, don't. I've done it, and I needed a second pot of tea.

4.5 It keeps IBM i security in charge

Mapepire doesn't bypass anything. It connects as a real IBM i user profile, so object authority still applies. It uses the same exit points as a typical JDBC application. In single mode the job runs as you, the user who signed on over SSH. For an AI that's allowed to run SQL, I'd say that's exactly what you want: BOB can only see what you can see.

5. Do I even need to install anything?

Good question, and the answer surprises people.

For BOB's normal use: probably not. Code for IBM i runs Mapepire in single mode by default and uploads the jar for you. What you do need, per IBM's Bob prerequisites, is:

  • IBM i 7.4 or higher (on 7.4, Db2 PTF group SF99704 level 13 or higher, and IBM recommends the latest Db2 group on any release)
  • SSHD running (STRTCPSVR SERVER(*SSHD)), from licensed program 5733-SC1, with user QSSHD enabled
  • Java on the IBM i, because Mapepire is a Java program. Code for IBM i lets you pick Java 8, 11, 17 or 21 in the connection settings (Mapepire Java runtime)

You install the Mapepire server (daemon mode) when:

  •  You use the IBM i MCP Server with BOB (or any other AI agent)
  • Lots of developers connect, and you'd rather have one shared server than a JVM per developer (Code for IBM i's docs point out that single mode means a JVM start on every connect, plus another one for the Db2 for i extension)
  • You want to write your own apps against Mapepire, like we'll do in section 7

6. Installing and starting the Mapepire server

From an SSH session on the IBM i (bash, with /QOpenSys/pkgs/bin on your PATH, as we set up in the Node.js course):

# 1. Install the Mapepire server RPM
yum install mapepire-server

# 2. Install Service Commander (if you haven't already)
yum install service-commander

# 3. Start Mapepire
sc start mapepire

# 4. Check it's alive
sc check mapepire

If you'd rather not use Service Commander, the RPM version can be started directly:

nohup /QOpenSys/pkgs/bin/mapepire &

The port

Mapepire listens on 8076 by default. The docs say it's not recommended to change it, but if you must, use the PORT environment variable, or edit the Service Commander definition with scedit mapepire (change the port in the check_alive field).

Certificates (TLS)

Mapepire's WebSocket connections are encrypted. You have three options for the certificate, in this order of preference:

  1. Let's Encrypt. If CertBot certificates exist under /etc/letsencrypt/live/, Mapepire picks them up automatically.
  2. Your own certificate, for example one exported from DCM. Put it in a JKS keystore at /QOpenSys/etc/mapepire/cert/server.jks, with store password mapepire, key password mapepire and alias mapepire:
dcmexport --password=changeit --dcm-store=system --format=pkcs12 mystore.p12

keytool -importkeystore -srckeystore mystore.p12 -srcstoretype pkcs12 \
-srcstorepass changeit -srcalias "mydcmalias" \
-destkeystore /QOpenSys/etc/mapepire/cert/server.jks -deststoretype JKS \
-deststorepass mapepire -destkeypass mapepire -destalias mapepire

(Replace changeit and mydcmalias with your own values. The mapepire passwords are the fixed values Mapepire expects.)

  1. Do nothing. If no certificate is configured, Mapepire generates its own self-signed certificate. Fine for a dev box, but your clients will have to trust it explicitly (section 7 shows how).

Starting it after an IPL

sc start starts it now, not at every IPL. One simple way to bring it back after an IPL is a job in your startup program, something like:

SBMJOB CMD(QSH CMD('/QOpenSys/pkgs/bin/sc start mapepire')) JOB(MAPEPIRE) JOBQ(QSYSNOMAX)

[CHECK] Run that under a profile that's allowed to start the service, and pick the job queue that suits your shop.

Is it really running?

From the shell:

sc check mapepire

From a 5250 green screen (yes, they still have their uses), NETSTAT OPTION(*CNN) and look for local port 8076 in Listen state. Or let SQL do it, which is very much the theme of this lesson:

SELECT LOCAL_ADDRESS, LOCAL_PORT, TCP_STATE
FROM QSYS2.NETSTAT_INFO
WHERE LOCAL_PORT = 8076;

You want to see a row with TCP_STATE = 'LISTEN'.

Pointing Code for IBM i (and BOB) at the server

In your Code for IBM i connection settings, turn on Connect to remote Mapepire server, leave the port at 8076, and connect. Code for IBM i then uses the WebSocket connection instead of starting single mode over SSH. One catch from the docs: server mode needs a password (it doesn't support SSH private keys), so you'll either type it each time or save it in the connection.

7. Talk to Mapepire yourself (Node.js 24)

The best way to understand what BOB is doing is to do it yourself. This little script runs on your PC (or any box with Node.js 24) and asks your IBM i the same kind of questions an AI tool would: "how's the system?" and "what does this table look like?"

It uses the FOODLIB.INGREDIENTS table from the Node.js course. Swap in your own library and table if you haven't built that one.

mkdir mapepire-demo && cd mapepire-demo
npm init -y
npm install @ibm/mapepire-js

Create a .env file (and don't commit it to Git):

DB2_HOST=myibmi.example.com
DB2_USER=NICK
DB2_PASS=secret

Now ask-ibmi.mjs. The .mjs extension lets us use import and top-level await without touching package.json:

// ask-ibmi.mjs - ask Db2 for i the questions an AI assistant would ask
import { Pool, getRootCertificate } from '@ibm/mapepire-js';

const creds = {
host: process.env.DB2_HOST,
port: 8076,
user: process.env.DB2_USER,
password: process.env.DB2_PASS,
};

// Self-signed certificate? Fetch it and trust it explicitly.
// getRootCertificate() returns undefined for a publicly trusted CA,
// so this does nothing if you're using Let's Encrypt or similar.
const ca = await getRootCertificate(creds);
if (ca) {
creds.ca = ca;
}

const pool = new Pool({ creds, maxSize: 3, startingSize: 1 });
await pool.init();

try {
// 1. How is the system feeling?
const status = await pool.execute(`
SELECT HOST_NAME, TOTAL_JOBS_IN_SYSTEM, ACTIVE_JOBS_IN_SYSTEM,
CONFIGURED_CPUS, SYSTEM_ASP_USED
FROM QSYS2.SYSTEM_STATUS_INFO`);
console.log('System status:');
console.table(status.data);

// 2. What does the INGREDIENTS table look like?
// Parameter markers, never string concatenation. BOB would approve.
const columns = await pool.execute(
`SELECT COLUMN_NAME, DATA_TYPE, LENGTH, NUMERIC_SCALE, IS_NULLABLE
FROM QSYS2.SYSCOLUMNS
WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?
ORDER BY ORDINAL_POSITION`,
{ parameters: ['FOODLIB', 'INGREDIENTS'] }
);
console.log('FOODLIB.INGREDIENTS columns:');
console.table(columns.data);
} catch (err) {
// The message includes the SQL error, sql_state and sql_rc from the server
console.error('Query failed:', err.message);
process.exitCode = 1;
} finally {
pool.end();
}

Run it with Node's built-in .env support:

node --env-file=.env ask-ibmi.mjs

Note what you didn't need: no ODBC driver, no DSN, no IBM i Access Client Solutions, no native compile. Just one npm package and port 8076. That, in a nutshell, is why AI tooling loves it.

Two other transports worth knowing: @ibm/mapepire-js can also connect in SSH single mode (no daemon needed, the same trick Code for IBM i uses), and if your Node.js code runs on the IBM i itself, local single mode spawns the server as a child process and uses the current job's user profile, with no credentials at all. Pooling only works with the WebSocket daemon, though.

8. Security: letting an AI near your database

An AI assistant that can run SQL and CL on your IBM i is wonderful right up until it isn't. Here's my checklist.

  • Use a sensible profile. In single mode BOB works as you. If your profile has *ALLOBJ, so does BOB. Develop with a normal developer profile, not QSECOFR. Please. I'm begging.

  • Keep TLS validation on. @ibm/mapepire-js validates the server certificate by default. The docs say never set rejectUnauthorized: false in production, because anyone who can intercept the traffic can then read the credentials. Trust a self-signed cert with getRootCertificate() instead, or better still, use a proper certificate.

  • Restrict who can connect. Mapepire reads user and IP rules from /QOpenSys/etc/mapepire/iprules.conf. The last matching rule wins:
    # Deny by default deny *@*
    # Only the AI service profile and developers, only from the office LAN allow BOBSVC@192.168.* allow NICK@192.168.*

  • Exit points still work, mostly. Mapepire uses the same exit points as a typical JDBC application. One gotcha from the docs: every client appears to come from 127.0.0.1, so IP-based exit program rules need to look at the CLIENT_WRKSTNNAME client special register instead. User-based rules just work.

  • Open only the port you need. If you run the daemon, port 8076 has to be reachable from the clients. Open it to the networks that need it, not the whole internet. If only SSH single mode is in use, you don't need 8076 open at all.

  • Use read-only where you can. Mapepire 2.5.0 (23 October 2026) added a read-only server mode and a "basic queries only" mode. 2.6.0 (17 November 2026) went further: it refuses IBM-supplied user profiles outright, removed the MP_UNSECURE switch for non-TLS mode, stopped logging the connection string (which contained the password) in daemon mode, and limits clients asking for access=read only to basic queries. If you run the daemon, upgrade:
    yum upgrade mapepire-server
    sc stop mapepire
    sc start mapepire
  • For the MCP route, the IBM i MCP Server's own read-only mode is the default. Keep it that way until you have a very good reason not to.

9. Troubleshooting

SymptomLikely cause and fix
BOB says "Failed to start Mapepire SQL job"Check Code for IBM i's version. In November 2026, Code for IBM i 3.0.13 uploaded mapepire-server-2.3.6.jar but looked for 2.3.5. Version 3.0.14 fixes it, but BOB pulls extensions from Open VSX, which still had 3.0.13. The workaround reported on BOB's GitHub (issue #3922) is to download the 3.0.14 VSIX and install it manually in BOB.
Connects, then SQL features failMapepire needs Java. In the Code for IBM i connection settings, set Mapepire Java runtime to a version that's actually installed (8, 11, 17 or 21). Plenty of people, me included, fixed it by picking the default Java.
Slow first connectThat's single mode starting a JVM, and the Db2 for i extension starts another one. Consider the shared daemon (section 6).
ECONNREFUSED on port 8076The daemon isn't running or a firewall is in the way. Run sc check mapepire, check QSYS2.NETSTAT_INFO, then check the firewall between you and the box.
Certificate errors (self-signed certificate, UNABLE_TO_VERIFY_LEAF_SIGNATURE)Your server uses the auto-generated self-signed certificate. Use getRootCertificate() as in section 7, or install a real certificate.
Login refused for a Q-profileThat's Mapepire 2.6.0 doing its job: IBM-supplied profiles are blocked. Use a real user profile. Also check iprules.conf.
Server mode keeps asking for a passwordExpected. Server mode doesn't support SSH private keys, so save the password in the connection or use single mode.
Something odd and you don't know whatIn BOB, open View → Output and look at the IBM Bob Premium Package for i channel (every tool call is logged, with a WARN if one hangs for 30 seconds) and the Code for IBM i channel (every CL, SQL and PASE command it runs).

Key takeaways

  • Mapepire is IBM's open-source Db2 for i access layer. A Java server on IBM i does the heavy lifting, and lightweight clients send JSON over SSH (single mode) or secure WebSockets (server mode, port 8076).
  • BOB's Premium Package for i connects through Code for IBM i, and Code for IBM i uses Mapepire for all its Db2 work. The optional IBM i MCP Server route uses Mapepire too.
  • An AI assistant needs lots of fast, small SQL questions about the catalog, IBM i services and your data, from a PC that isn't your IBM i. Mapepire gives it that with no driver to install, one protocol, and IBM i security still in charge.
  • For BOB's basic use, SSH plus Java is usually enough. Install mapepire-server and start it with sc start mapepire when you want a shared daemon or the MCP Server.
  • Lock it down: a sensible user profile, TLS with proper certificate validation, iprules.conf, read-only modes, and Mapepire 2.6.0 or later.

Quick quiz

Next steps

In the next lesson we'll put this to work and connect BOB to the IBM i MCP Server, with a read-only service profile and a couple of custom YAML SQL tools, so BOB can check system health without being able to drop anything. Until then, try the ask-ibmi.mjs script against your own tables, and have a look in the Code for IBM i output channel next time BOB answers a database question. Watching the SQL go past is surprisingly addictive.

Put the kettle on. You've earned it.

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}
>