start here

start using PM2 with your agents

sign up, open a project, and add PM2 to its setup script in settings → server.

Start 7-day trial with PM2
integrationstechnologyupdated
schematic diagram of the work aldena agents do through PM2
PM2

pm2 ai agent: agents that keep a process running and read its logs

add pm2 to a project's setup script and its agents start long-running processes, list what is running, read the logs, and stop everything cleanly when done.

runs on
conversation sandbox
installed by
setup script
category
server

pm2 solves a small problem that blocks a lot of work: an agent needs the app to still be running in the next message. installed in each conversation's sandbox it puts pm2 on the path for every agent in the project.

what agents do with it

an agent starts a service with pm2 start, checks what is up with pm2 list, and reads accumulated output with pm2 logs. that last one matters more than it sounds. a background process that failed two requests ago left its stack trace somewhere, and pm2 is where the agent goes to find it. pm2 kill stops everything at the end, which keeps the conversation's sandbox in a known state for the next task.

the matching skill

pm2 ships with a skill of the same name. it carries starting and listing processes, inspecting output with pm2 logs, stopping everything with pm2 kill, and the node.js dependency. skills load only for the agents you assign them to.

example tasks

  • 01

    run the api in the background and check the webhook path works.

    the agent starts the service under pm2 in the conversation's sandbox, calls the webhook from the same machine, and reads the process logs to confirm what arrived.

    bashread
  • 02

    the worker keeps dying overnight. find out what kills it.

    it reads the accumulated pm2 logs in the conversation's sandbox, finds the unhandled rejection that ends the process, and fixes the handler.

    bashgrepedit

what to know before installing

the project needs a sandbox, and node.js must come earlier in the setup script. pm2 is small and sits comfortably on the small size alongside the app it supervises. the sandbox sleeps 30 minutes after its last command, which stops running processes, so agents start them again with pm2 after it wakes.

how to install PM2

PM2 goes in the project's setup script, not once per team and not on your laptop.

  1. give the project a sandbox

    PM2 runs in each conversation's sandbox, on your team's own sandbox provider account. an owner or admin connects a provider once on the team's providers page, then picks it and a default size for the project, at creation or later in settings → server. a project with no sandbox has nowhere to run it.

  2. add it to the setup script

    settings → server holds the project's setup script, a bash script that runs once on each new sandbox, in /project, with sudo. add PM2's install commands there and save.

  3. the next sandbox runs it

    the script runs when a conversation's sandbox is created or reused, on the conversation's first turn. settings shows the last run with its exit code and output, and a failed run leaves the sandbox usable rather than blocking the project.

  4. agents use it through bash

    from then on every agent in the project reaches PM2 with the bash tool, on the same filesystem as the checkout they are working in. the conversation's sandbox keeps it between turns, sleeping when idle and waking with the next one.

where PM2 actually lives

each conversation in a project gets its own sandbox on your team's sandbox provider account, and the project's setup script in settings → server decides what is on it. two projects never share a filesystem, so a version pinned for one client cannot collide with another's.

the sandbox provider bills its machine time to your team's account while it runs, and aldena adds nothing. the sizes are on isolated projects, and what agents may run in the sandbox is governed by the project's tool permissions.

faq

why does an agent need a process manager?

because a shell command ends when the command ends. pm2 start keeps the app running in the conversation's sandbox between messages, so an agent can start a service in one step and call it in the next without holding a terminal open.

what does the agent do with pm2 logs?

reads them. pm2 logs shows the output of a process that has been running in the background, which is how an agent finds the exception that happened three requests ago rather than only the one it triggered itself.

does pm2 need anything installed first?

yes, node.js. it installs through npm, so node.js has to come earlier in the project's setup script. installing node.js before pm2 avoids that round trip.

will a process keep running and cost me money?

only while the sandbox is awake. your sandbox provider bills its machine time to your team's account while it runs, and the sandbox sleeps 30 minutes after its last command, which stops every process. pm2 kill stops everything sooner when the work is finished.

ready when you are

spin up your first project.

one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.