Agent 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.

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

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: solucetechnologies/agent-portabase:latest
        restart: always
        volumes:
            # Mount the DB config file
            - ./databases.json:/app/src/data/config/config.json
        extra_hosts:
            # Allows the agent to contact the host's 'localhost'
            - "localhost:host-gateway"
        environment:
            TZ: "Europe/Paris"
            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
PROJECT_NAME=portabase-agent

Start

docker compose up -d

Database management

Once the agent is installed, tell it which databases to back up. The CLI provides a db module to manage the databases.json safely.

Add a database

This command launches an interactive assistant to add a connection (Postgres, MySQL, MariaDB).

# Syntax: portabase db add <agent-folder>
portabase db add my-agent

You will be asked for:

Type: PostgreSQL, MySQL or MariaDB.
Host: localhost (if on the same machine) or an IP address.
Port: e.g. 5432.
Credentials: User and Password.

List configured databases

To see which databases are managed by this agent:

portabase db list my-agent

Remove a database

portabase db remove my-agent

After adding or removing a database, it's recommended to restart the agent so changes are applied immediately: portabase restart my-agent

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.

Agent Installation

On this page