Add a custom service

For credentials and connection strings that don't fit a built-in service in the catalog (a Stripe test key, an internal API token, a webhook URL), set the env vars directly on the sandbox.

Per-sandbox env vars

agentry env set STRIPE_SECRET_KEY                # hidden prompt for the value
agentry env set STRIPE_WEBHOOK_SECRET            # another hidden prompt
agentry env set STRIPE_PUBLISHABLE_KEY pk_test_xxx

Omit the VALUE to be prompted with hidden input — that's the recommended way for anything secret-shaped so it stays out of shell history.

To set values on a specific sandbox other than the current pinned one:

agentry env set STRIPE_SECRET_KEY --sandbox quill

The variable becomes available immediately to new processes started in the sandbox. Existing processes (a dev server already running) pick up the change when they restart.

Confirming what's set

agentry env ls
agentry env ls --sandbox quill

Lists the env var names plus a length indicator. Values are not printed.

Deployment env

The same env carries through when you deploy from the sandbox — the deployment form pre-fills the Env tab with everything in the source sandbox. You can edit or override each value at deploy time and click Save and redeploy.

For values that should ONLY exist in production (real Stripe live keys, prod database creds), don't set them on the sandbox. Add them directly in the deployment's Env tab in the dashboard.

When you want this to be a real binding

The CLI's service bind command works against a fixed service catalog (see agentry service ls). If the same custom credentials show up in every project — for example a company-internal API token your apps all need — and you want them to land in every new sandbox automatically, the right approach today is:

• A short shell script that runs agentry env set for each value, run once per new sandbox.
• Or set the vars in the deployment's Env tab when you ship.

First-class custom bindings are on the roadmap. Until then, per-sandbox env is the path.

Security

Env values set this way are stored encrypted at rest on the cluster and decrypted into the sandbox's process env at runtime. They appear via printenv from any shell inside the sandbox — same blast radius as any env-based secret. Treat your sandbox shell access accordingly.

Common patterns

Stripe test keys

agentry env set STRIPE_SECRET_KEY                    # hidden prompt
agentry env set STRIPE_PUBLISHABLE_KEY pk_test_xxx
agentry env set STRIPE_WEBHOOK_SECRET                # hidden prompt

An internal API

agentry env set ACME_API_URL https://api.acme.internal
agentry env set ACME_API_TOKEN                       # hidden prompt

A webhook target

agentry env set SLACK_WEBHOOK_URL                    # hidden prompt

Telling the agent

The agent doesn't automatically discover ad-hoc env vars set this way — they aren't in sandbox_create's bindings response, which lists catalog services only. Name them in your prompt so the AI knows to read them:

Use STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET from env for Stripe — they're already set, don't ask for them.

Next

• Bindings overview — the catalog-backed model.
• Add a database — for built-in DB services.
• Add an AI provider — for AI keys.