npm.io
1.0.1 • Published yesterdayCLI

devlai-agent

Licence
ISC
Version
1.0.1
Deps
4
Size
36 kB
Vulns
0
Weekly
0
SummaryDependencyVersions

Devlai Agent

The Devlai Agent is a lightweight Node.js daemon that runs on a user's VPS and connects the VPS to the Devlai platform.

It runs as a systemd service and is responsible for:

  • Sending VPS system metrics to Devlai.
  • Discovering and reporting Docker containers.
  • Collecting Docker container statistics.
  • Streaming assigned container logs to Devlai.
  • Authenticating with the Devlai Core API using an agent API key.
  • Automatically restarting itself if the process crashes.

The agent is designed to run continuously in the background with minimal configuration.

Requirements

The VPS must have:

  • Linux
  • Node.js
  • npm
  • Docker
  • systemd
  • Network access to the Devlai API
  • Permission to access the Docker socket

The agent currently targets Linux VPS environments.

Installation

Install the agent globally using npm:

npm install -g devlai-agent

Verify the installation:

devlai-agent --version

Initialization

After installation, initialize the agent using an API key generated from the Devlai dashboard:

sudo devlai-agent init --api-key <YOUR_API_KEY>

Initialization performs the following steps:

  • Validates the API key against the Devlai API.
  • Retrieves the agent/VPS information.
  • Detects the Docker socket.
  • Creates the agent configuration directory.
  • Writes the agent configuration.
  • Creates the systemd service.
  • Reloads systemd.
  • Enables the service to start automatically on boot.
  • Starts the agent.

After successful initialization, the agent runs automatically in the background.

Configuration

The agent configuration is stored at:

/etc/devlai-agent/config.json

Example:

{
  "label": "production-vps",
  "agentApiKey": "your-agent-api-key",
  "dockerSocketPath": "/var/run/docker.sock"
}

The configuration file is created with restricted permissions.

The configuration directory:

/etc/devlai-agent

uses 0700 permissions.

The configuration file uses 0600 permissions.

The API key should therefore only be readable by root.

systemd

The agent runs as:

devlai-agent.service

The systemd unit is installed at:

/etc/systemd/system/devlai-agent.service

Check the agent status:

sudo systemctl status devlai-agent

View agent logs:

sudo journalctl -u devlai-agent -f

Restart the agent:

sudo systemctl restart devlai-agent

Stop the agent:

sudo systemctl stop devlai-agent

Disable automatic startup:

sudo systemctl disable devlai-agent

The service is configured with:

Restart=always
RestartSec=10

Therefore, systemd automatically restarts the agent if the process exits unexpectedly.

What the Agent Does

Telemetry

The agent periodically collects:

  • System metrics.
  • Docker containers.
  • Container CPU usage.
  • Container memory usage.

Telemetry is sent periodically to the Devlai Core API.

The agent also receives the current agent state from the API.

If the agent is disabled from the Devlai dashboard, the agent stops its operation.

Docker Containers

The agent discovers Docker containers through the Docker Engine API.

It reports information such as:

  • Docker container ID.
  • Container name.
  • Image.
  • Container state.
  • CPU usage.
  • Memory usage.

The Docker socket is automatically detected during initialization.

Container Logs

The agent can stream logs from containers assigned to the agent.

Logs are:

  • Read from Docker.
  • Demultiplexed into stdout/stderr.
  • Parsed into individual log entries.
  • Assigned a log level.
  • Buffered locally.
  • Sent to the Devlai API in batches.

Example log entry:

{
  "level": "ERROR",
  "message": "Database connection failed",
  "timestamp": "2026-08-19T12:34:56.789Z",
  "source": "api-container"
}

Supported levels:

DEBUG
INFO
WARN
ERROR

stderr output is treated as ERROR.

Log Buffering

Logs are not sent individually.

The agent flushes buffered logs periodically.

The current limits are:

Maximum in-memory entries: 10,000
Maximum entries per request: 500
Flush interval: 5 seconds

These limits prevent a noisy container or an unavailable backend from causing unbounded memory growth.

When the backend is unavailable

If sending a log batch fails:

  • The failed batch is returned to the local buffer.
  • New logs continue entering the buffer.
  • Once the buffer reaches its maximum size, the oldest entries are dropped.

The agent prioritizes recent logs over old logs.

This means log delivery is best effort and does not provide durable log storage.

Logs can therefore be lost when:

  • The Devlai API is unavailable for an extended period.
  • The agent process crashes.
  • The VPS is shut down.
  • The local log buffer reaches its maximum capacity.
Agent Shutdown

The agent handles:

SIGTERM
SIGINT

During shutdown it:

  • Stops the telemetry loop.
  • Stops log streaming.
  • Closes active Docker log streams.
  • Attempts to flush remaining buffered logs.
  • Exits.

This allows systemd to shut down the agent cleanly.

Edge Cases
Docker is not running

The agent cannot discover containers or collect container statistics if Docker is unavailable.

The agent reports the failure through its normal error handling.

Docker socket is unavailable

If the Docker socket cannot be detected during initialization, initialization fails.

The agent cannot operate correctly without access to the Docker Engine.

Container stops

When a container stops, its log stream ends and the agent cleans up the associated stream.

If the container becomes assigned again later, the agent can open a new stream.

Container restarts

If a container restarts while keeping the same Docker ID, the existing log stream ends.

The agent detects the ended stream and can establish a new stream during the next assignment reconciliation.

Container is removed and recreated

A recreated container receives a new Docker ID.

The agent treats it as a different container.

The Devlai backend must update the container assignment to the new Docker ID before the new container's logs can be streamed.

Devlai API is temporarily unavailable

Telemetry failures are handled without immediately terminating the agent.

Log batches are temporarily retained in memory.

The agent continues operating and retries during subsequent cycles.

Devlai API key becomes invalid

If the API reports an authentication failure, the telemetry loop backs off for a longer period instead of continuously sending failed requests.

The API key can be rotated using:

sudo devlai-agent rotate --api-key <NEW_API_KEY>
Agent is disabled

If the Devlai backend reports that the agent is disabled, the agent stops its operation.

The agent does not continue sending telemetry or logs while disabled.

VPS reboots

The systemd service is enabled during initialization.

After a reboot, systemd automatically starts:

devlai-agent.service
Network is temporarily unavailable

The agent does not require the network to remain continuously available.

Network requests fail normally and are retried through subsequent telemetry/log cycles.

API Key Rotation

Rotate an existing agent API key:

sudo devlai-agent rotate --api-key <NEW_API_KEY>

The new key is written to:

/etc/devlai-agent/config.json

Restart the service after rotation if the running process has already loaded the old configuration:

sudo systemctl restart devlai-agent
Uninstallation

Stop the service:

sudo systemctl stop devlai-agent

Disable it:

sudo systemctl disable devlai-agent

Remove the systemd unit:

sudo rm /etc/systemd/system/devlai-agent.service
sudo systemctl daemon-reload

Remove the configuration:

sudo rm -rf /etc/devlai-agent

Finally uninstall the npm package:

sudo npm uninstall -g devlai-agent

Architecture

The agent is intentionally kept as a small standalone Node.js daemon.


                    ┌──────────────────────┐
                    │   Devlai Core API    │
                    └──────────┬───────────┘
                               │
                    HTTP / Webhooks
                               │
                               ▼
┌─────────────────────────────────────────────────────┐
│                    Devlai Agent                     │
│                                                     │
│  ┌──────────────┐       ┌────────────────────────┐  │
│  │ Telemetry    │       │ Log Streaming          │  │
│  │              │       │                        │  │
│  │ System       │       │ Docker logs            │  │
│  │ Containers   │       │ Parsing                │  │
│  │ Stats        │       │ Buffering              │  │
│  └──────────────┘       │ Batching               │  │
│                         └────────────────────────┘  │
│                                  │                  │
│                         Docker Engine API           │
└──────────────────────────────────┼──────────────────┘
                                   │
                                   ▼
                           Docker Socket

The agent is responsible for VPS-side operations.

The Devlai Core API remains responsible for:

  • Authentication.
  • Agent management.
  • Container assignments.
  • Telemetry persistence.
  • Log ingestion.
  • SSE communication.
  • Workspace isolation.
  • Higher-level orchestration.

The agent does not contain AI logic.

Security

The agent API key is stored locally in:

/etc/devlai-agent/config.json

with restrictive permissions.

The agent requires root privileges during initialization because it needs to:

  • Write system configuration.
  • Install the systemd unit.
  • Access system-level Docker resources.

The running service itself should only receive the permissions required to communicate with Docker and the Devlai API.

License

ISC