Lastboard Agent

Secure Docker bridge for Lastboard — monitor and control remote containers without exposing the Docker daemon.

     

---

What is this?

The Lastboard Agent runs on any remote Docker host as a lightweight container. It mounts the local Docker Unix socket and exposes a secure, token-authenticated HTTP API that Lastboard uses to monitor and control containers on that machine.

Instead of exposing the Docker daemon over TCP — which is inherently dangerous — Lastboard communicates only with the agent. The agent acts as a controlled, authenticated proxy: it forwards only the specific operations Lastboard needs and nothing more.

No database. No config files. Restart or replace it at any time — it's fully stateless.

---

Requirements

• Docker installed on the remote host
• Port 2375 reachable from the Lastboard host (or any custom port you configure)

---

Quick Start

Docker Compose (recommended)

Copy the following docker-compose.yml to your remote host:

services:
  lastboard-agent:
    image: git.codigosh.com/codigosh/lastboard-agent:latest
    container_name: lastboard-agent
    ports:
      - "2375:2375"
    environment:
      - TOKEN=change-this-to-a-secret-token
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

Three things to know before running:

• TOKEN — the shared secret Lastboard will use to authenticate. Generate a strong one:

  openssl rand -hex 32
  

• ports — change 2375:2375 if you need a different port. The right side must match PORT if you override it.
• volumes — /var/run/docker.sock must not be changed. This gives the agent access to the local Docker daemon.

Then start it:

docker compose up -d

Docker Run

docker run -d \
  --name lastboard-agent \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e TOKEN=your-secret-token \
  -p 2375:2375 \
  --restart unless-stopped \
  git.codigosh.com/codigosh/lastboard-agent:latest

---

Connecting to Lastboard

1. Open your Lastboard dashboard
2. Add a Docker widget, or open the settings of an existing one
3. Click Add Host
4. Select type: Lastboard Agent
5. Enter the host address: your-server-ip:2375
6. Enter the token you chose
7. Click Add — your containers will appear immediately

---

Environment Variables

Variable	Default	Description
TOKEN	(required)	Bearer token for authentication. Use a strong random value.
PORT	2375	Port the agent listens on.
SOCKET_PATH	/var/run/docker.sock	Path to the Docker Unix socket.

---

Security

• Allowlisted by design — the agent forwards only the exact Docker API calls Lastboard needs and rejects everything else with 404, even with a valid token:

  Method	Path	Operation
  GET	/containers/json	List containers
  GET	/containers/{id}/stats	Read CPU / memory stats
  POST	/containers/{id}/start	Start a container
  POST	/containers/{id}/stop	Stop a container
  POST	/containers/{id}/restart	Restart a container

  Creating, deleting, exec-ing into containers, or any other Docker operation is not reachable through the agent. A leaked token can only list and control the lifecycle of existing containers — never compromise the host.

• Bearer token on every request — validated with constant-time comparison to prevent timing attacks. Unauthenticated requests get 401 without revealing which routes exist.

• Use a strong random token (minimum 32 characters recommended: openssl rand -hex 32).

• The Docker socket is mounted read-only and the container runs with no other access.

• For extra protection, restrict port 2375 in your firewall to allow connections only from your Lastboard host IP.

• The agent runs as root inside the container by default so it can read the Docker socket. To run unprivileged, grant only the host's docker group via group_add (see docker-compose.yml).

---

Health Check

The /health endpoint requires no authentication and can be used to verify the agent is running:

curl http://your-server:2375/health

{"status":"ok"}

---

Building from Source

git clone https://git.codigosh.com/CodigoSH/lastboard-agent.git
cd lastboard-agent
go build -o lastboard-agent .
TOKEN=my-secret ./lastboard-agent

Requires Go 1.26+. No external dependencies.

---

License

Apache 2.0 — see LICENSE.

---

A project by CodigoSH — built to last.