Installing an agent

What the agent is and why it connects out#

The agent is the process that runs pipeline steps on your infrastructure. It connects to the master itself: it sends a heartbeat over HTTPS at a regular interval, claims waiting jobs on those heartbeats, and sends logs and results back.

That means:

• You do not open any incoming connection to the machine or cluster the agent runs on. It works behind NAT and firewalls.
• The agent only needs to reach your EJO address (https://acme.ejocloud.com) over HTTPS. If you use a proxy, allow that address.
• The master never connects to your cluster and never asks for a kubeconfig.

Prerequisites#

• An environment for the agent to register into. If you have none, create one under Infrastructure > Environments > New environment. See Environments.
• Tokens and manifests for agent installs are shown to admin users only.
• For Kubernetes, permission to kubectl apply on the cluster; for Docker, a Linux server with Docker installed.

Pick an install method#

Press Install agent on the environment page. There are three tabs:

Install on Kubernetes#

1. Open the Kubernetes (otomatik kurulum) tab.

2. Fill in the fields:

   • Agent name: the name the agent shows in the console.
   • Namespace (optional): where the agent runs. Left empty, ejo-agent is used and created if missing.
   • Master URL (optional override): the address the agent uses to reach the master. On EJO Cloud the default is your EJO address; you rarely need to change it.
   • Registry pull credential: on EJO Cloud the credential for pulling the agent image is already provided; you can leave these fields empty.
   • Preview namespaces (Review Apps): check it if this agent will create per-PR preview namespaces. Leave it off for production agents. See Preview apps.

3. Press Generate manifest.

4. Run the command shown on the page with your own kubectl access:

   kubectl apply -f "https://acme.ejocloud.com/api/v1/agent-installations/<id>/manifest?key=<secret-key>"
   

5. When the agent sends its first heartbeat, the page updates by itself. Once the install is done, View agent takes you to the agent page.

Warning: The URL in the command contains a secret key and the manifest carries the agent's token. Do not share the URL. The manifest cannot be downloaded again after it was used.

The manifest creates the namespace, the agent's ServiceAccount, a Role limited to the agent namespace, the Secrets it needs and the agent Deployment. Use Show manifest to review it before applying.

Tip: The agent can read the Secrets in its own namespace. Keep your application secrets out of the agent's namespace.

Preview namespaces and the admission policy#

With Preview namespaces (Review Apps) checked, the manifest adds ClusterRoles and a ValidatingAdmissionPolicy so the agent can only create and delete namespaces labeled ejo.dev/preview=true. The admission policy needs Kubernetes 1.30 or newer; on an older cluster, uncheck Admission policy for preview namespaces.

Install on Docker#

1. Open the Docker / Manuel tab.

2. Check Agent name and the master URL field (Master URL (agent'ın göreceği adres)). The master URL must be the address of your EJO as seen from the agent's machine: https://acme.ejocloud.com.

3. Press Registration token oluştur. The token is added to the commands; it works once, is valid for 1 hour by default and is not shown again once you leave the page.

4. Copy the command under Docker container and run it on your Docker host. It looks like this:

   docker run -d --name ejo-agent \
     -e EJO_AGENT_MASTER_URL=https://acme.ejocloud.com \
     -e EJO_AGENT_NAME=production-agent \
     -e EJO_AGENT_ENVIRONMENT_ID=<environment-id> \
     -e EJO_AGENT_REGISTRATION_TOKEN=<registration-token> \
     -v ./ejo-agent-data:/etc/ejo-agent \
     -v ejo-agent-cache:/var/cache/ejo \
     -e EJO_AGENT_CACHE_DIR=/var/cache/ejo \
     -v /var/run/docker.sock:/var/run/docker.sock \
     <agent-image>
   

   Use the image name the console shows.

• -v /var/run/docker.sock:/var/run/docker.sock lets the agent build and run containers with the host's Docker daemon.

• -v ./ejo-agent-data:/etc/ejo-agent is required: the registration token works only once, so the agent writes the identity it received there and does not try to register again when the container restarts.

• -v ejo-agent-cache:/var/cache/ejo and EJO_AGENT_CACHE_DIR=/var/cache/ejo keep the agent's local step cache on a volume, so it survives a container restart or an image upgrade. Without them the cache lives inside the container and starts empty each time. EJO also keeps a copy of every cache on the master (the remote cache), so a new agent warms up from there; see the cache limits under Organization settings.

Run it as a binary#

The Config dosyası (manuel / systemd) option gives you the content of /etc/ejo-agent/config.json and the command to start the agent:

{
  "master_url": "https://acme.ejocloud.com",
  "name": "production-agent",
  "environment_id": "<environment-id>",
  "heartbeat_interval": "10s"
}

sudo EJO_AGENT_REGISTRATION_TOKEN=<registration-token> ./ejo-agent --config /etc/ejo-agent/config.json

The agent registers on first start and writes the token it received back into the same file.

Agent settings#

Docker and binary installs also read these environment variables:

Watch agent status#

Infrastructure > Agents lists every agent with its version and last heartbeat.

• A new agent shows as PENDING until its first heartbeat.
• An agent that misses its heartbeat window turns OFFLINE. It returns to ONLINE by itself when it reconnects.
• A waiting deployment is claimed on the next heartbeat of an online agent in its environment.

Deleting an agent removes its record; if it is still running, it cancels its running job and exits on its next heartbeat.

Upgrade an agent#

Kubernetes agents#

1. Open the agent under Infrastructure > Agents.
2. Enter the new image under Upgrade image. Left empty, EJO's default agent image is used.
3. Confirm. The task shows "rolling out" first and "done" once the new agent process connects to the master.

Notes:

• An upgrade cannot start while the agent runs a job; try again when it is done.
• If the new process does not connect within 5 minutes, a "stalled" warning appears: the new pod did not come up and the old one keeps running.
• Build and Image digest on the agent page should change after the upgrade. If they stay the same, the console warns you; the tag you used most likely still points to the old image.

Cache on Kubernetes agents#

The Deployment mounts an emptyDir at /var/cache/ejo for the local step cache, sized from the environment's Cache max (GB). It is not a persistent volume on purpose: the durable copy is the remote cache on the master, which a restarted pod restores from. Container steps run in their own Job pod; the cache and needs_artifacts are restored into that pod and saved from it, so they work the same as on a Docker agent. This needs an agent upgraded to a version that advertises remote_cache.

Step logs#

An agent that advertises log_append sends a step's log as it grows, only the new bytes, instead of the whole log every second. Each step's log is capped by Step log max (MB) under Organization settings (default 10). A step that writes more keeps its first half and its last half in the console, with one marker line where the middle was cut, and the full log is uploaded to the blob store: use Download raw log on the step. Raw logs are deleted together with the log text by Log retention. Older agents keep sending full snapshots; the master cuts those to the same cap.

Docker and binary agents#

Upgrading the image from the console is for Kubernetes agents only. To upgrade a Docker agent, recreate the container with the new image; as long as you keep the same ./ejo-agent-data volume, the agent keeps its identity and does not register again. For a binary install, replace the binary and restart the service.

Note: Some features (external secret managers, the automatic SBOM scan, debug sessions) need a recent agent. With an older agent the deployment stops with an "upgrade the agent" message, or the feature is skipped.

Next steps#

• Environments
• Bind a repository
• Troubleshooting: agent offline