agent
Create and configure an agent and its databases.
The agent is the connector installed next to your databases. It needs an Edge Key, created in the Dashboard when you add an agent. New to agents? Follow Set up an agent.
agent create
Creates the agent folder, generates .env, databases.json and docker-compose.yml, and creates the external Docker network portabase_network if needed. In interactive mode it then offers to add databases ("Add a database?").
portabase agent create [OPTIONS] NAME| Option | Description | Default |
|---|---|---|
NAME | Folder to create, e.g. prod-db-01. Required. | — |
--key-stdin | Read the Edge Key from standard input — see secrets. | asked |
--key <str> | Edge Key from the Dashboard (Base64 or JSON with serverUrl, agentId, masterKeyB64). Prefer --key-stdin. | asked |
--tz <str> | Agent timezone (TZ). | UTC |
--polling <int> | Polling frequency in seconds (POLLING). Must be ≥ 1. | 5 |
--log-level <str> | debug, info, warn or error (LOG_LEVEL). | info |
--host-gateway / --no-host-gateway | Map localhost in the agent to the Docker host, to back up a database on the host itself (extra_hosts: localhost:host-gateway). | false |
-s, --start | Start the agent right after creation. | false |
-f, --force | Overwrite an existing folder without asking. | false |
-y, --yes | Skip the "Apply this configuration?" confirmation. | false |
See Agent environment variables for the meaning and accepted ranges of each variable.
Example
portabase agent create my-agentNon-interactive / CI example: see Concepts.
agent show
Displays the agent's settings grouped by section (Agent, Network, Storage, Resilience) — secrets are masked — followed by a table of its databases.
portabase agent show <AGENT_PATH>agent set / agent unset
Change one or more settings of an existing agent, then re-render .env and docker-compose.yml.
portabase agent set <AGENT_PATH> KEY VALUE [KEY VALUE ...]
portabase agent unset <AGENT_PATH> KEY [KEY ...]unset removes the variable from .env, so the agent falls back to its own default. Core settings are required and cannot be unset (only changed).
| Key | Type | Written to | Core |
|---|---|---|---|
key | Edge Key (validated, secret) | EDGE_KEY | Yes |
tz | text | TZ | Yes |
polling | integer ≥ 1 | POLLING | Yes |
log_level | debug info warn error | LOG_LEVEL | Yes |
host_gateway | boolean | extra_hosts in docker-compose.yml | Yes |
data_path | text | DATA_PATH | No |
tmpdir | text | TMPDIR | No |
retry_attempts | integer ≥ 1 | RETRY_ATTEMPTS | No |
retry_backoff_ms | integer ≥ 1 | RETRY_BACKOFF_MS | No |
ca_bundle | host path (must exist) | read-only volume + SSL_CERT_FILE | No |
Booleans accept true/false, yes/no, on/off, 1/0.
portabase agent set ./my-agent polling 30 log_level debug
portabase agent set ./my-agent tmpdir /scratch host_gateway true
portabase agent unset ./my-agent tmpdir retry_attempts
portabase restart ./my-agentApply with portabase restart <AGENT_PATH> (why).
agent set <PATH> key <EDGE_KEY> puts the key in your shell history. To rotate the key without leaving a trace, prefer editing EDGE_KEY in .env and running portabase build <PATH>.
agent db add
Adds a database to an agent. It either creates a new database container in the agent's compose (--mode new, handy for tests and local projects) or registers an existing server (--mode existing).
portabase agent db add [OPTIONS] <AGENT_PATH>| Option | Description | Default |
|---|---|---|
-e, --engine <key> | Database engine (see table below). Applies to all engines. | asked |
--mode <new|existing> | new = container created by the CLI, existing = your own server. Applies to all engines except docker-volume. | new |
--label <str> | Display name. Applies to existing mode and docker-volume (generated automatically in new mode). | External DB (Docker Volume for volumes) |
--host <str> | existing mode: host or IP. Default localhost. | localhost |
--port <int> | existing mode: port. | engine's standard port |
--database <str> | existing mode: database name (Redis/Valkey: database index). | 0 (Redis/Valkey only) |
--user <str> | existing mode: username (Redis/Valkey: optional). | — |
--password-stdin | existing mode: read the password from standard input. | — |
--password <str> | existing mode: password. Visible in shell history — prefer --password-stdin. | — |
Passing a flag that does not apply to the chosen engine and mode fails with Option(s) not applicable to … and lists the valid ones.
Supported engines
--engine | Modes | Default port | Notes |
|---|---|---|---|
postgresql | new, existing | 5432 | Supports -o keep_ownership and -o clean_mode. |
postgresql-cluster | new, existing | 5432 | Uses pg_dumpall: the user must be a superuser. |
mysql | new, existing | 3306 | new mode runs a mariadb:latest container. |
mariadb | new, existing | 3306 | |
sqlite | new, existing | — | File mounted into the agent under /config/. |
firebird | new, existing | 3050 | |
mongodb | new, existing | 27017 | --auth/--no-auth in new mode. For SRV (Atlas), use --port 0. |
redis | new, existing | 6379 | --auth/--no-auth in new mode. Backup only. |
valkey | new, existing | 6379 | --auth/--no-auth in new mode. Backup only. |
mssql | new, existing | 1433 | new mode runs azure-sql-edge with the sa user. |
docker-volume | — | — | Mounts /var/run/docker.sock into the agent automatically. |
Example
printf '%s\n' "$PG_PASSWORD" | portabase agent db add ./my-agent \
--engine postgresql --mode existing \
--label "Production app" --host 10.0.0.12 --port 5432 \
--database app --user backup --password-stdin \
-o clean_mode=drop_schemas -o keep_ownership=falseApply with portabase restart <AGENT_PATH>.
agent db list
Displays a table of the agent's databases: display name, database, type, host:port (or file / volume), user, non-default options and the first 8 characters of the ID.
portabase agent db list <AGENT_PATH>agent db remove
Removes a database from databases.json. For a database created with --mode new, its service is also removed from docker-compose.yml and its variables from .env.
portabase agent db remove [OPTIONS] <AGENT_PATH>| Option | Description | Default |
|---|---|---|
-i, --id <str> / --name <str> | Database to remove: full ID, ID prefix, or display name. Without it, an interactive menu is shown. | — |
--purge-volume | Also delete the Docker volume of a database created by the CLI. | false |
-y, --yes | Skip the confirmation. | false |
portabase agent db remove ./my-agent --id 3f2a91c4 --yes
portabase agent db remove ./my-agent --name "Production app"
portabase agent db remove ./my-agent --id db-pg --purge-volume --yesData is kept unless you ask otherwise
Without --purge-volume, the data volume of a managed container (<project>_<service>-data) is kept; the CLI prints the docker volume rm command to delete it later. With --purge-volume, the volume and all its data are deleted immediately — this is irreversible.
If a value matches several databases (e.g. a short ID prefix), the command fails and asks you to use the full ID.
Last updated on