Installation

The Portabase Agent is a lightweight connector that runs on your servers. Its role is to:

Secure the connection with the Dashboard.
Execute backup tasks.
Manage local (or remote) databases.

It can manage existing databases (already installed on your server) or create new ones via Docker.

Need to be update, check docker install

The CLI guides you step by step: it configures the agent and offers to add databases immediately.

Ensure the CLI is installed first. If it isn’t, follow the instructions here.

Retrieve your Edge Key

Before starting, go to your Portabase Dashboard, create a new Agent and copy its Edge Key.

Create the Agent

Run the command on the server where you want to install the agent:


portabase agent my-agent

The CLI will ask for your Edge Key. Paste it and confirm.

Configure Databases

The wizard will ask whether you want to configure a database. You have two choices:

Docker (New Local Container): The CLI will add a PostgreSQL or MariaDB container to the agent's docker-compose.yml. Great for starting a fresh local project.
Manual (External/Existing): To connect an already existing database on your server (or a remote RDS/managed instance). You will need to provide host, port and credentials.

Start

If you didn't start the agent at the end of installation:


portabase start my-agent

For a manual installation, create the file structure and configure the network so the agent can reach your local databases.

File structure

Create a folder and prepare required files:

mkdir portabase-agent && cd portabase-agent
touch docker-compose.yml .env databases.json

The databases.json file must exist (even empty) before starting the container, otherwise the agent may fail to start.

Initialize the JSON file with an empty object:

echo '{"databases": []}' > databases.json

Docker configuration

Create the docker-compose.yml. Note the use of extra_hosts so the agent can reach the host's services via localhost.

docker-compose.yml

name: portabase-agent

services:
    app:
        container_name: portabase-agent
        image: portabase/agent:latest
        restart: always
        volumes:
            # Mount the DB config file
            - ./databases.json:/config/config.json
        extra_hosts:
            # Allows the agent to contact the host's 'localhost'
            - "localhost:host-gateway"
        environment:
            TZ: "Europe/Paris"
            LOG: info
            # If you prefer using .toml files, please check configuration section
            # DATABASES_CONFIG_FILE: "config.toml"
            EDGE_KEY: "${EDGE_KEY}"
        networks:
            - portabase

networks:
    portabase:
        name: portabase_network
        external: true

Note: Create the portabase_network manually if it does not exist: docker network create portabase_network.

Environment variables

Add your key to the .env file:

.env

EDGE_KEY=your_edge_key_here

Start

docker compose up -d

Development

To set up the agent in a development environment:

Clone the repository

git clone https://github.com/Portabase/agent-rust.git
cd agent-rust

Build the agent

cargo build

Start in development mode

docker compose up

Lifecycle commands

As with the dashboard, you can control the agent with standard commands:

Command	Description
`portabase start <path>`	Start the agent.
`portabase stop <path>`	Stop the agent.
`portabase logs <path>`	Check whether the agent is connected to the dashboard ("Ping server").
`portabase uninstall <path>`	Remove the agent and its configuration.

Installation

On this page