Authentication

Put a login screen in front of any app you deploy — email and password out of the box, plus social login (Google, GitHub, Microsoft, or any OpenID Connect provider). You don't write auth code. agentry runs a login layer in front of your container and tells your app who's signed in.

This is different from a deployment's access mode. Access modes are a coarse gate on the whole app (public / org-only / one shared passphrase). Authentication gives you real, individual user accounts — sign-up, sign-in, password reset, the works.

How it works

When you turn auth on, every request to your app passes through agentry's login layer first:

visitor → login layer → (signed in?) → your app
                       → (not signed in?) → login / sign-up screen

• A visitor with no session is shown a sign-in / sign-up page.
• Once they're signed in, the request is passed to your app — along with a few headers telling your app exactly who they are.
• Your app never has to render a login form, hash a password, or run an OAuth dance. That all happens in the layer in front.

The login pages, sessions, password reset, OAuth, rate-limiting, and account lockout are all handled for you.

How your app sees the signed-in user

On every authenticated request, your app receives these headers:

Header	Contains
X-Forwarded-User	A stable unique user ID
X-Forwarded-Email	The user's email
X-Forwarded-Name	Display name
X-Forwarded-Provider	How they signed in — password, google, github, …

Your code just reads those headers. For example, "show the logged-in user's email in the header bar" becomes reading X-Forwarded-Email. When you prompt your agent to build something that needs the current user, tell it: "the signed-in user is in the X-Forwarded-Email and X-Forwarded-User request headers."

There's a built-in cheat sheet

Inside any sandbox, the agent can run docs_read("skills/auth") to get the exact, current conventions for reading these headers. Point it there if it's unsure.

What you need

• A database bound to your server — auth stores user accounts in it. Postgres, MySQL, or MongoDB all work. Bind one with agentry service bind postgres (see Add a database).
• The agentry CLI, signed in (agentry login).
• Optional, to unlock password-reset emails: an SMTP service bound (agentry service bind smtp).

Turn it on

agentry auth enable

This runs a quick fitness check against your bound database (can it connect, create a table, write, read, clean up?), generates a signing secret for sessions, and switches new sandboxes — and any running ones — into authenticated mode. It then prints a summary of what's available:

✓ email + password sign-in, sessions
– password reset: bind smtp to enable → `agentry service bind smtp`
– social login:   `agentry auth providers add google ...`

From here:

• Email & password — what you get immediately, plus password reset and the security model.
• Social login — add Google, GitHub, Microsoft, Apple, or a custom OIDC provider.

Where auth settings live

Auth is configured per server and per profile — the same scoping as your env vars and service binds. Switching profiles gives you an independent auth setup (handy for keeping a dev configuration separate from production). Check the current state any time:

agentry auth status

auth: ENABLED on server "prod" (profile "main")
  db binding: postgres
  AUTH_SECRET: <set>
  providers:   google, github

Turning it off

agentry auth disable

New sandboxes go back to passing traffic straight through with no login screen, and the setting is cleared from running sandboxes. Your user table in the database is left untouched, so you can re-enable later without losing accounts.

Next

• Email & password
• Social login
• Add a database — the prerequisite store for accounts.