Profiles & per-server config

Your environment variables and service bindings aren't global — agentry remembers them per server. This page explains that (it trips people up), then shows how profiles add an optional second dimension. Lots of examples.

The one thing to understand

Bindings are scoped to the server. When you bind a service or set an env var, agentry saves it for the server that's currently active. Switch to a different server and your bindings switch with it — automatically.

agentry server use laptop
agentry service bind postgres        # → enter your LOCAL dev database

agentry server use prod
agentry service bind postgres        # → enter your PRODUCTION database

Now you have two Postgres bindings, one per server. You never re-enter them:

agentry server use laptop            # sandboxes here get the dev database
agentry server use prod              # sandboxes here get the prod database

Same command, same variable name (DATABASE_URL), different value per server — because each server keeps its own copy. Every new sandbox on a server inherits that server's bindings.

What a profile is

A profile is a named set of that config — env vars, service binds, and auth settings. You start on a profile called default, and most people never need another one.

A profile adds a second dimension on top of per-server. So the full picture is a grid: (server × profile) → your bindings.

	profile default	profile staging
server: laptop	dev DB, test keys	—
server: prod	prod DB, live keys	staging DB, test keys

• Switching servers is automatic — whatever server is active decides which column-of-bindings applies.
• Switching profiles is manual — agentry profile use <name> — and lets you keep more than one set on the same server.

The active profile is a single global choice; its contents are still per-server. So prod + profile default is a different set of bindings than prod + profile staging.

When you'd use a second profile

You don't need one to use different servers — that's handled for you. Reach for a profile when you want two configs on the same server, for example:

• A staging profile on your prod box that points at a staging database, so you can deploy a staging build beside production.
• A client-a and client-b profile when one server hosts work for different clients with different API keys.

If that's not you, stay on default and forget profiles exist.

The commands

agentry profile                 # what am I on? → "default (server=prod)"
agentry profile list            # every profile on this machine
agentry profile use staging     # switch the active profile
agentry profile create staging  # make a new, empty profile
agentry profile show staging    # list a profile's env + binds
agentry profile copy default staging   # clone one profile into another
agentry profile delete staging  # remove it (not 'default' or the active one)

Example 1 — one profile, many servers (the common case)

You develop on your laptop and deploy to a Hetzner box. You never touch profiles.

# laptop: wire up local services
agentry server use laptop
agentry service bind postgres        # postgresql://localhost:5432/dev
agentry env set STRIPE_KEY           # hidden prompt → your test key

# prod box: wire up the real ones
agentry server use prod
agentry service bind postgres        # your managed prod database URL
agentry env set STRIPE_KEY           # hidden prompt → your live key

From now on, the active server decides everything:

agentry server use laptop   # new sandboxes get the dev DB + test key
agentry server use prod     # new sandboxes get the prod DB + live key

One profile (default), zero re-entering.

Example 2 — two profiles on one server

Your prod box should host both production and a staging copy of an app.

agentry server use prod

# production config lives on the default profile
agentry service binds                # shows the prod database, live keys

# create a staging profile and point it at staging services
agentry profile create staging
agentry profile use staging
agentry service bind postgres        # staging database URL
agentry env set STRIPE_KEY           # test key

# build a staging sandbox while this profile is active…
# …then flip back to production config:
agentry profile use default

Same server, two independent sets of bindings — switch with one command.

Example 3 — start from a copy

A new profile starts empty. To make a near-duplicate, copy an existing one and change only what differs:

agentry profile copy default staging   # clone everything
agentry profile use staging
agentry service bind postgres          # override just the database

Example 4 — see exactly what's active

$ agentry profile
default (server=prod)

$ agentry service binds
postgres   DATABASE_URL
openai     OPENAI_API_KEY

$ agentry env ls
DATABASE_URL
OPENAI_API_KEY
STRIPE_KEY

agentry env ls and agentry service binds always reflect the current (server, profile) pair. Change either and the lists change.

Good to know

• New sandboxes inherit the active (server, profile) bindings automatically — that's the whole point. Existing sandboxes keep what they were created with.
• A bind without --sandbox saves to the current server + profile. Add --sandbox <id> to set something on just one sandbox without touching the profile.
• default is protected — you can't delete it, and you can't delete the profile you're currently using. Switch away first.
• Auth follows the same scoping. Authentication is configured per (server, profile) too, so a staging profile can have its own login setup.

Next

• How bindings work — what a binding does inside a sandbox.
• Multiple servers — prototyping on one, deploying on another.
• CLI reference — the full command list.