Run-agent introduction

Pikacloud Run-agent helps you managing your own servers. Run-agent is responsible of the following tasks:

  • Control the execution of Docker containers with clustering features like replication, failover handling and containers placement policies.
  • Sandbox mode: one-click container launch with direct access to a container shell and live logs.
  • Stream container logs to Pikacloud. Log archiving policicies available.
  • Build and maintain a mesh encrypted network between your servers to interconnect Docker containers.
  • Auto attach Docker Containers to Pikacloud Load balancers with SSL Offloading.
  • Produce real time monitoring for your server system and hardware metrics.
  • Build Docker Image from a Git repository and push to a Docker registry like Pikacloud Private Registry.

Run-agent listens two channels: Docker events and Pikacloud tasks. Once a container is configured (Pikacloud side), Run-agent receives a task from Pikacloud in order to boot a new container matching configuration defined in Pikacloud. If the container crashes or if the hosting server become unavailable, Pikacloud asks to an other healthy agent to run the same exact container.

Quick start

Run-agent documentation

Run-agent installation


Run-agent is itself a Docker container. To start your first agent, paste the following command in your server terminal:

bash <(curl -sL

Once connected you can view your new agent in your agents list:

How to verify run-agent is running

Check container is up and running:

docker ps | grep run-agent
a2c4dc67e2e6        pikacloud/run-agent:latest                               "/bin/sh -c 'run-a..."   2 weeks ago         Up 2 weeks                                                                run-agent

Check run-agent logs:

docker logs run-agent
[Display run-agent logs]
docker logs --tail=10 -f run-agent
[Display run-agent logs and keep the logs flowing]

Run-agent configuration settings

You can configure run-agent with the following environment variables:
Name  Role Default
PIKACLOUD_API_TOKEN required API private token to authenticate with Pikacloud API None
PIKACLOUD_AGENT_LABELS List of strings separated by a comma "aws,eu-west-1a,nginx,magento" None
LOG_LEVEL Defines log level (debug for the most verbose logging level) info

If you want to change configuration and run-agent is already running, first remove its container (docker rm -vf run-agent) before relaunching it.

Full list of Run-agent environment variables is available on Github.

Run-agents private mesh networks

Building our own private and encrypted mesh networks

Running run-agent in your server allow you to do:

  • Networking between containers running in multiple hosts, fully managed by your run-agents
  • Multiple Run-agents automatic discovery
  • Isolated and encrypted networks for Docker containers
  • Containers are associated with DNS name
  • Multiple container replicas form a Round-robin DNS entry with multiple records. Achieve easily load balancing or failover with this simple strategy.

By running Run-agent, your servers build a private and encrypted Super Network. Agents connect to other agents in order to create and dynamicaly grow or shrink a mesh network.

You can attach containers to one or more networks shared between multiple hosts.

Network communications between containers of the same network are isolated from other networks.

Once a new agent start, it receive a list of your other agents and try to connect to them. Other agents will try to connect to this new agent too if necessary.

You have to allow your server to receive trafic for the following ports: TCP 6783, UDP 6783 and UDP 6784.

Pikacloud Sandbox

Pikacloud Run-agent can run and monitor containers but it can also build Docker Images from a Git repository and starts this container following the build. Once started you will have access to a terminal inside the container and will able to watch the container logs.

These are typical use cases of Pikacloud Sandbox:
  • Quick boot of a container: like docker run, you can start a container in one step. Your Run-agent can start a container with a Docker Image pulled from a registry or with the result of a docker build of a Git repository.
  • Developer usage: test software bundled in a Docker image by selecting a specific Git reference. For example, you can run multiple sandbox of the same repository built with specific Git branches.
  • Testing your software: as Pikacloud Sandbox can build and run a container from Git source, you can use Pikacloud Sandbox for tasks dealing with sofware testing.

Building Docker Images

Pikacloud Docker Images Builder is docker build as a service, running in your own servers.

Pikacloud Docker Images Builder is a service handled by your run-agents. Docker images are built by run-agent in your own servers.

Once built, images are pushed to the private Docker Registry of our choice like Pikacloud Registry service.

How Run-agent billing works

Like other Pikacloud services, Run-agent is billed once it boot and register with Pikacloud. pricing details »

We regurarly count how many agents you run and multiply hour of usage. Monthly invoices contain detailed usage.

You can create and operate as many containers, images builder and sandbox as your servers can handle them. Only running and connected run-agents are billed.

Run-agent security information

Pikacloud ensures strict rules of internal security to ensure customers data integrity and operational resilience of services.

In practise, Run-agent relies on the following standards:

  • Run-agent is itself a Docker Container,
  • Run-agent source code is open source and relies on a documented and stable API,
  • Run-agent do not execute direct shell command from Pikacloud: Run-agent polls Pikacloud on a regular basis for actions to do and sent local information to Pikacloud API. Only pre-defined operation can be run localy.
  • All Run-agent communications are encrypted.
  • Data requiring a higher level of privacy are encrypted for storage and exchange.
  • Keys rotation is used when required

If you discover a security problem in our softwares, fell free to contact us first.

Remote shell access and logs of container in Sandbox Mode

Real time monitoring of the host running Run-agent

Keep an eye on your infrastructure with the container dashboard