Project config

A project's config is its pom.yml (see the reference). This page covers changing it from the app: editing, adding and removing repos, and handing a config to a teammate. Most of it lives in Settings > Project and the command palette.

Edit the config

Open it any of these ways:

• Open Project Config in the command palette.
• Edit pom.yml in the project menu (click the project name in the top bar).
• Settings > Project > Config File > Edit...
• pom config edit in a terminal opens it in $EDITOR, then checks it still loads.

The config stays editable from main, even though main's other files are read-only.

Checked saves

Every save of pom.yml is checked before it is written. A save that does not parse, or that would leave a working config unable to load, is refused and nothing is written: the editor says Not saved: <the problem>. When the config was already broken, a save goes through, so you can fix it in steps.

After a change

The app picks up a saved config at once ("pom.yml reloaded"), whether it was saved in Pomelo or in another editor. It then:

• rewrites the env files of every workspace from the new config, and
• lists the running services whose command or env no longer matches what they were started with, in a notice (N services still run the old config) with a Restart button.

Nothing restarts on its own.

Repositories

Settings > Project > Repositories lists each repo of the config with its service count and where it is checked out: not cloned into main, in main, or in N of M workspaces besides main.

Add a repository

Add Repository (Settings > Project > Add..., or the command palette) takes a Git URL or folder and an optional Alias. Pomelo clones it into main, detects its services, and writes its entry into pom.yml. Under Also check it out in, tick the workspaces that should get it too. Then choose:

• Let Claude wire its env and shared services - Claude opens in a terminal to finish the new entry (env, shared services, setup) and runs the config doctor until it reports no errors.
• Review its entry in the config afterwards - the entry opens in the editor for you.

Rename or remove

• Rename Alias... gives the repo a new alias and rewrites every reference to it in the config ({{api.server.url}} and the like).
• Remove... takes the repo out of the config. It is refused while other repos still refer to it. Its worktree is removed from workspaces where it has no changes and kept where it does; main's clone stays on disk.

Workspaces choose their repos

A new workspace checks out only the repos picked when it was created. To add more of the config's repos to one later, right-click it in the sidebar and choose Add Repos....

Main is expected to have every repo. When the config names a repo main has no clone of (a teammate added it, or the config came from a bundle), main's row shows not cloned: <repo>. Clone Missing Repos into Main (command palette), Settings > Project > Clone Missing Repos or the row's Clone Missing Repos... asks where to clone each one from, with a URL guessed from main's other repos.

Write the env

A repo's env holds its variables and decides which files they land in. Values are templates, resolved for each workspace:

# Flat: written to .env.local
env:
  DATABASE_URL: "postgres://{{shared.postgres.url}}/{{db.main}}"

# One map per file; "*" is the base every file starts from
env:
  "*":
    REDIS_URL: "redis://{{shared.redis.host}}:{{shared.redis.port}}/{{shared.redis.slot}}"
  .env.development.local:
    DATABASE_URL: "postgres://{{shared.postgres.url}}/{{db.main}}"
  .env.test.local:
    DATABASE_URL: "postgres://{{shared.postgres.url}}/{{db.test}}"

A file's own value overrides "*". Pomelo writes the files only where the repo already keeps env files (a root with .env or .env.development, or apps/<name>/.env) and in a service's dir; services get the resolved env injected either way. Edit env in pom.yml, never the generated file.

For a workspace on branch feat/login of session: myproject, with databases: { main: "{{branch.safe}}" }:

env:
  DATABASE_URL: "postgresql://{{shared.postgres.url}}/{{db.main}}"
  REDIS_URL: "redis://{{shared.redis.host}}:{{shared.redis.port}}/{{shared.redis.slot}}"

becomes

# Auto-generated by pom. Do not commit.
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/myproject_feat_login
REDIS_URL=redis://127.0.0.1:6379/3

Only env values are resolved. A cmd is run as written: use $PORT, $BIND_IP or any env var the service gets.

When the config is invalid

Pomelo checks the file when it loads it. An invalid file is not used, and each problem is listed with where it is:

Problem	Example message
A colon-form template	repo "api" env.DATABASE_URL: {{conn:postgres}} is removed - use {{shared.NAME.url}}
A profile with no environment	repo "api": environment "staging" not defined
A shared service with both or neither of image and cmd	shared service "mock-as": set either image (a Docker container) or cmd (a command), not both
An image-only field on a cmd service	shared service "mock-as": ports is only for an image; a cmd service uses port
A cmd-only field on an image service	shared service "postgres": port is only for a cmd; an image service uses ports
A repo that is not in repos	shared service "mock-as": repo "auth" is not in repos
A cmd service on a port another shared service wants	shared services "mock-as", "stub" all want port 4010

The config doctor looks further: missing tools (Docker, a cmd service's program), repos that are not cloned, secrets with no value, and shared services nothing references.

Tidy the config

pom config normalize drops keys the format no longer uses and rewrites old colon tokens ({{conn:x}}) to dot notation.

A project from an older version that still has a pom.d/ folder is folded into pom.yml the first time it loads. Blocks keep their text and comments where the fragments do not overlap, and the originals are kept beside it as pom.d.bak and pom.yml.bak.

Config bundles

Share a project's setup with a teammate from Settings > Project > Config Bundle (or Export Config / Import Config in the palette):

• Export... saves the config as plain YAML, or, with Include secrets, as a .pombundle with the project's secrets sealed under a password (AES-256-GCM). Share the password separately.
• Import... reads a pom.yml or .pombundle. Choose Replace my pom.yml (the old one is kept as pom.yml.bak) and, for a bundle, Store these secrets in this project. Or pick Adapt with Claude to have Claude merge it into your config.

After importing a config that names repos you don't have, use Clone Missing Repos into Main.

From a terminal

The pom CLI has the same operations:

pom config path
pom config edit
pom config normalize
pom config export [--secrets]
pom config import <file>
pom apply [branch]      # check out repos the config added but a workspace lacks