Any number of identities, chosen by directory and generated from one registry,
~/.config/devbox/identities.conf. The devbox holds no private key for any of them; you (a forwarded 1Password agent) and an agent session (HTTPS, per-operation tokens) use them differently.
Related: Secrets · Security Model · CLI Reference · Connecting
Any number of identities, chosen by directory. Each is a [slug] block in ~/.config/devbox/identities.conf, read by
devbox-identities, the one script that turns the registry into everything below. The devbox holds no private key for
any of them; you and an agent session use them differently.
| Who | Default identity (everywhere) | A second identity (~/projects/work/**, org your-org) |
|---|---|---|
You (manual, ssh -A devbox or laptop) |
SSH git@github.com:, forwarded id_personal.pub (the host's plain key), author Your Name <you@example.com>, signed |
SSH git@github.com:, forwarded id_work.pub (ssh -P work tags it), author Your Name <you@work.example.com>, signed |
Agent session (omp/claude/codex launcher) |
HTTPS, token from devbox-git-credential, author your-agent <your-agent@users.noreply.github.com>, unsigned |
HTTPS, same helper, author your-app[bot] <00000000+your-app[bot]@users.noreply.github.com>, unsigned |
A dir in identities.conf picks the identity both ways: includeIf gitdir: in your own ~/.gitconfig, the same
prefix in agent.gitconfig's includeIf for an agent. Exactly one block omits dir — that one is the default,
catching every tree no other block claims; the rest match by longest prefix, so one tree can nest inside another.
Nesting works because of two things the generators do, not because git does it for you. git applies every matching
includeIf and the last one read wins, so every identity with a dir gets a file of its own — even one that only
inherits the default author, which is then written out explicitly — and the includes are emitted shortest dir first,
whatever order the blocks appear in the config. A tree inside another identity's tree therefore ends on its own name,
email, signing key and agent author.
Org includes (org-<slug>.gitconfig, below) are separate from this nesting: hasconfig:remote.*.url: matches a
remote's URL text, not a directory, so they apply to a repository wherever it lives — and, unlike gitdir:, from the
very first git clone, since a clone writes the remote before it fetches. Both kinds of includeIf land in
~/.gitconfig; the tree-based ones are written first, so an org include — when one applies — is read last and wins.
~/.config/devbox/identities.conf is the single source. ~/.local/libexec/devbox-identities (DEVBOX_IDENTITIES_FILE
overrides the path) is its one reader on both machines: ~/.ssh/config, ~/.gitconfig's includeIf chain,
allowed_signers, both agent gitconfigs, and which GitHub token or App a directory gets all come out of it.
Important
You create the registry by copying home/.config/devbox/identities.conf.example; neither container/bootstrap.sh nor
./bin/devbox agent install writes it for you — the example is a valid file, so seeding it would quietly make
Your Name <you@example.com> this machine's identity instead of failing the check. Both print the cp command while
it is missing.
Both machines need the same file; ./bin/devbox sync identities copies the laptop's copy to the devbox and re-runs
bootstrap so everything derived from it catches up (see Laptop install).
One [slug] block per identity, slug lowercase [a-z][a-z0-9_]*:
| Field | Meaning | Default |
|---|---|---|
dir |
Directory prefix that selects this identity. Must be absolute or start ~/, and contain no whitespace — it also becomes a gitdir: pattern and a config key, and a relative path resolves differently for git than for the token resolver, so check rejects both. Omit on exactly one block — that one is the default, catching every tree no other dir matches. Longest matching prefix wins. |
none on the default block |
name, email |
Your git identity in that tree. Required. | — |
pubkey |
The laptop's public authentication key, one line, as in ~/.ssh/id_<slug>.pub. Devbox only: it holds no private key. Empty disables SSH-as-you for that tree. |
empty |
signing_pubkey |
The matching public signing key. GitHub registers authentication and signing keys separately; signing with the auth key shows Unverified. | empty |
agent_name, agent_email |
Author of agent commits in that tree — the identity's App bot, <app-slug>[bot] and <bot-user-id>+<app-slug>[bot]@users.noreply.github.com (gh api 'users/<app-slug>[bot]' --jq .id). |
the default identity's |
app |
Directory holding the identity's GitHub App app-id + app.pem (mode 600) — see devbox-git-credential. Every identity gets one: PATs are read-only, so it is the only way an agent writes. |
none — agents in that tree can only read |
host |
Forge host. A GitHub Enterprise host moves the HTTPS rewrite, the API this identity's credentials use, and every orgs pattern onto that instance. |
github.com |
orgs |
GitHub owners (orgs or user logins) whose repositories this identity pushes to — space- or comma-separated, spelled exactly as GitHub spells them (matching is case-sensitive). Required for any identity whose pubkey differs from its host's plain key, since nothing else would ever select it. See Cloning. |
none — the plain key and the default identity's author |
Everything else is derived from the slug alone:
| Derived from the slug | Where |
|---|---|
| Key files | ~/.ssh/id_<slug>.pub / ~/.ssh/signing_<slug>.pub (see the key files below) |
| ssh tag | <slug>, when its key differs from its host's plain one (devbox-identities get <slug> tag, Cloning) |
| GitHub token | GH_TOKEN_<SLUG> in ~/.config/devbox/secrets.env (see Secrets) |
| Generated gitconfigs | agent-<slug>.gitconfig / user-<slug>.gitconfig / org-<slug>.gitconfig (below) |
Tip
Adding an account is therefore a block in identities.conf, a token in secrets.env, and the two public keys — no
code change anywhere. See Laptop install and Secrets for the
exact steps.
devbox-identities is symlinked into ~/.local/bin, so it answers by name in any shell. devbox-identities check
validates the file:
- exactly one default
- no duplicate slugs
- every
dirabsolute and whitespace-free name/emailpresent- the default identity's
agent_name/agent_emailpresent - every
orgsentry a valid GitHub owner name - no org claimed by two identities on the same host
- an
orgsentry on any identity whosepubkeydiffers from its host's plain key (otherwise nothing ever selects that key)
check is what a broken registry fails on: every identity-derived step of bootstrap is then skipped as one block, so
a bad edit costs configuration, never SSH access.
devbox-identities inspects the resolved registry and prints exactly what bootstrap installs:
| Command | Purpose |
|---|---|
devbox-identities list |
Inspect the resolved registry |
devbox-identities for <dir> |
Inspect the resolved registry — who owns a directory |
devbox-identities get <slug> <field> |
Inspect the resolved registry — one field |
devbox-identities show <slug> |
Inspect the resolved registry — every resolved field for an identity |
devbox-identities org-urls <slug> |
Inspect the resolved registry — the four hasconfig: patterns for an identity's orgs |
devbox-identities alias-remotes |
Inspect the resolved registry — old clones left on a git@<slug>.<host>: remote |
devbox-identities local-user-overrides |
Inspect the resolved registry — clones whose own .git/config sets user.name/user.email |
devbox-identities render ssh-config |
Print exactly what bootstrap installs |
devbox-identities render agent-gitconfig [slug] |
Print exactly what bootstrap installs |
devbox-identities render user-gitconfig <slug> |
Print exactly what bootstrap installs |
devbox-identities render org-gitconfig <slug> |
Print exactly what bootstrap installs |
devbox-identities render allowed-signers |
Print exactly what bootstrap installs |
Plain GitHub URLs, chosen by directory, from a pane with the 1Password agent forwarded (ssh -A devbox, next section):
git clone git@github.com:<your-github-username>/<repo> ~/projects/<your-github-username>/<repo> # default identity
git clone git@github.com:<org>/<repo> ~/projects/work/<repo> # work identity - <org> in its `orgs`No alias host, ever — the remote is the same text whichever identity clones it. Two independent things key off that text and pick the right identity, both live from the very first clone:
- Which key SSH offers.
org-work.gitconfigsetscore.sshCommand = ssh -P workfor this repository, which selectsMatch host github.com tagged workin~/.ssh/config—id_work.pub, not the host's plain key. Only an identity whose key differs from the plain one gets a tag (devbox-identities get work tag; empty means no tag, and none needed). - Which author and signing key sign it.
~/.gitconfig'sincludeIf "hasconfig:remote.*.url:<pattern>"(one per URL form git accepts for a GitHub remote —git@github.com:<org>/**,git@github.com:/<org>/**(the form JetBrains IDEs clone with),ssh://git@github.com/<org>/**,https://github.com/<org>/**, fromdevbox-identities org-urls work) loadsorg-work.gitconfig.hasconfig:matches the remote URL the clone itself writes, before the first fetch — unlikeincludeIf gitdir:, which only starts matching once the directory already exists. - Matching is exact text, case-sensitive:
orgs = your-orginidentities.confmust be spelled exactly as GitHub spells the owner (ApiTreeCZ, notapitreecz). - Directory-independent: an org's repository gets that org's identity wherever it is cloned to. The
dirprefix only matters as a fallback — an identity's own non-org repositories inside its tree.
gh repo clone works the same way for every identity — gh config sets git_protocol ssh, and the URL it clones with
is the same git@github.com:<owner>/<repo> either way.
Confirm which identity a repo picked up (your manual identity in ~/.gitconfig, not an agent session's — see Agent
sessions):
cd ~/projects/work/<repo>
git config user.email # you@work.example.com
git config user.signingkey # /home/dev/.ssh/signing_work.pub
git config core.sshCommand # ssh -P work
git remote -v # git@github.com:<org>/<repo> - no alias hostThe devbox generates and holds no private GitHub key. A push, signed commit, or cloning a private repo as you borrows the laptop's running 1Password agent, forwarded for one connection:
ssh -A devboxcontainer/sshd_config sets AllowAgentForwarding yes for this. The devbox's ~/.ssh/config (bootstrap, rendered
from identities.conf by devbox-identities render ssh-config) has one plain Host <host> block per forge naming the
key most identities on it share (IdentityFile + IdentitiesOnly yes), plus a Match host <host> tagged <slug> block
per identity whose key differs, selected by the ssh -P <slug> an org's core.sshCommand passes — so ssh offers
exactly one key, never whichever the forwarded agent happens to list first.
Without -A, a manual git push or signed commit fails on purpose — no key to answer. Ordinary herdr panes and
./bin/devbox shell do not forward the agent: herdr's SSH connection never sets ForwardAgent, and the laptop's
Host devbox block keeps it off — only an explicit ssh -A devbox does.
Warning
Accepted limit. For that connection's lifetime the forwarded socket is open to every process in the devbox, not
just the shell you forwarded it into. Git in an agent session can't use it (fenced to HTTPS); a raw ssh from
anything else can. 1Password approves per key and per application, not per use, so a key your terminal app is
already approved for signs without a prompt. See Security Model.
Every agent session — an OMP, Claude Code or Codex process started through its launcher, and everything it shells out
to (gh, wt, lazygit, git itself) — runs under five exports the launcher sets for its process tree, before
exec-ing the real binary. All launchers (omp-launcher, claude-launcher, codex-launcher in
~/.local/libexec/devbox-agent, each reached as omp/claude/codex through a symlink) are three lines around one
shared body, agent-launch, so the agents can never drift apart:
| Export | Value | What it does |
|---|---|---|
GIT_CONFIG_GLOBAL |
~/.config/devbox/git/agent.gitconfig |
replaces ~/.gitconfig, not merged |
GIT_SSH_COMMAND |
…/devbox-git-no-ssh |
refuses every SSH remote, exit 255 |
GIT_TERMINAL_PROMPT |
0 |
missing credential errors, never hangs |
GH_CONFIG_DIR |
~/.config/devbox/gh |
gh sees no login: shim token, or none |
PATH |
launcher's directory and its fenced/ |
puts the gh and git shims in front |
Nothing outside that process tree sees any of it — a clone opened in a pane or IDE keeps its SSH remote, forwarded agent, signed commits.
It also clears what the shell that started it may carry for you: an IDE terminal's askpass (GIT_ASKPASS,
SSH_ASKPASS, VS Code's VSCODE_GIT_* — it answers git's credential prompts with your own GitHub login), your
GITHUB_TOKEN, GH_ENTERPRISE_TOKEN and GITHUB_ENTERPRISE_TOKEN, SSH_AUTH_SOCK (a forwarded agent on the devbox;
on the laptop the session's own ssh still reaches 1Password through IdentityAgent), and GIT_CONFIG_COUNT/
GIT_CONFIG_PARAMETERS, which outrank every config file. GH_TOKEN stays: the gh shim honours an explicit one as a
deliberate choice. Clearing is a default, not a boundary — a forwarded agent's socket is still under ~/.ssh/agent/
(OpenSSH >= 10.1), on the bind mount, for anything that looks (accepted limit 2).
codex-launcher also drops OPENAI_API_KEY and CODEX_API_KEY, so a key exported from secrets.env or a shell is
never billed instead of Codex's ChatGPT sign-in (the mirror of claude-launcher dropping ANTHROPIC_API_KEY). And it
passes --no-daemon: since 0.157 an interactive codex attaches to one shared background server, which runs every
attached session under the environment of whatever started it — the desktop app or a bare codex would mean a session
without the fence. With the flag a launcher session runs its own embedded server even while a shared one is up.
GIT_CONFIG_GLOBAL beats includeIf via GIT_CONFIG_COUNT/GIT_CONFIG_KEY_*, which ignores includeIf gitdir: and
can't follow the repo tree like agent.gitconfig's includeIf. Pointing GIT_CONFIG_GLOBAL at a file that itself
includeIfs a second makes the rule work under an env override.
Note
A repository's own .git/config user.email wins over GIT_CONFIG_GLOBAL — local always outranks global in git.
Stock git behavior.
A tool inside a session can start a child process with an environment of its own choosing. OMP's Python eval kernel
passes on an allowlist (PATH, HOME, SSH_AUTH_SOCK, LC_*, XDG_*, PI_* …) and drops all five exports: git
there reads ~/.gitconfig and commits under your name, and gh gets the read-only PAT, or on the laptop without
GH_CONFIG_DIR your own login. PATH is the one part such a filter keeps, so the fence travels on it:
agent_fence also prepends ~/.local/libexec/devbox-agent/fenced, which holds a git shim and is on no other PATH
— not your own shell's on either machine, not devbox.sh's. When GIT_CONFIG_GLOBAL is unset, the git shim and the
gh shim (on finding fenced/ on the PATH) run agent_fence again before the real binary, so git commits as the
bot and gh takes the App token again. A GIT_CONFIG_GLOBAL that is set to anything else, a test suite's
/dev/null say, is a choice and stays. A child that also rebuilds PATH from scratch is out of reach of this.
The Claude desktop app starts its sessions itself, from launchd's environment, so no launcher runs and git and gh
would act as you. On the laptop ./bin/devbox agent install therefore also adds a SessionStart hook to
~/.claude/settings.json: ~/.local/libexec/devbox-agent/claude-session-env sources agent-launch, runs the same
agent_fence the launchers run, and writes its exports and unsets (plus DEVBOX_ENV=laptop and guarded PATH
prepends for the gh and git shims) into the session's CLAUDE_ENV_FILE, which Claude Code runs before every Bash command. The
entry is appended next to the herdr, moshi-hook and IDE ones, never in the preset: sync claude replaces arrays
whole. Under a launcher it writes the values the session already has.
It covers Bash commands only — git, gh, wt run by the agent. Claude Code's own process, its other hooks and MCP
servers keep the app's environment, and so does anything the app itself runs outside the Bash tool. Without a readable
agent.gitconfig the hook writes nothing and fails, so DEVBOX_ENV stays empty and the agent stops before any push.
devbox doctor laptop fails while the entry is missing.
There is no counterpart to claude-session-env for Codex, so sessions the ChatGPT/Codex desktop app starts are not
fenced — git and gh act as you. This is an accepted limit: Codex's shell_environment_policy in
~/.codex/config.toml could set the git exports for every command, but not put the gh shim ahead on the PATH (it
takes literal values), and that file is the desktop app's own, so applying it would need a TOML merge - not done.
They still read ~/.codex/AGENTS.md (the laptop agent context), which tells an agent with an empty DEVBOX_ENV to stop
before any git push or gh write, and they still load the guardrail rules in ~/.codex/rules/devbox.rules
(Toolchain). Only a codex started through its launcher is fenced; start Codex sessions
from a terminal.
~/.config/devbox/git/ is a directory of mode 500 holding both gitconfigs at 444, because GIT_CONFIG_GLOBAL points
into it: a git config --global … anywhere in a session rewrites the agent's own configuration. That is not
hypothetical, and it needs no agent — on this laptop ~/.bash_profile sources ~/.extra, which ends in
git config --global user.name "$GIT_AUTHOR_NAME"
git config --global user.email "$GIT_AUTHOR_EMAIL"so every login bash started inside a session stamped the owner's name and email into agent.gitconfig, and five
commits in a personal repo carried it before anyone looked. git creates a lock file beside the config it rewrites, so a
directory without write permission turns that into an immediate error: could not lock config file — loud, at the
offending call, instead of silent drift. Reading is unaffected. Fix the dotfile too (the
GIT_AUTHOR_*/GIT_COMMITTER_* assignments above those lines serve your own shell perfectly well);
./bin/devbox doctor laptop flags the pattern. The launcher additionally unsets GIT_AUTHOR_NAME,
GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL, which outrank every configuration file, and refuses
to start at all if the gitconfig is missing — no session may run without an identity, because that is what invites
something to set one. Both sides of doctor check the mode and compare the files against the repo templates; the
installers (./bin/devbox agent install, ./bin/devbox bootstrap) lift the mode, regenerate, and lock it again.
omp update picks what to replace by looking omp up on the PATH, and takes over whatever it finds — a plain file in
place, a symlink through its target. Every launcher is on that PATH, so each drops its own entries for update: any
lookup then lands on the real install — bun/npm-managed or ~/.local/bin/omp for OMP, the native install's
~/.local/bin/claude for Claude Code, the standalone install's ~/.local/bin/codex for Codex (Homebrew's on a laptop
that has it from there) — which is what the updater must replace. The same passthrough covers claude update and
codex update; Claude's background auto-update re-points ~/.local/bin/claude itself, and Codex's installer and
codex update re-point ~/.local/bin/codex, which is exactly why no launcher symlink ever lives there. The other
exports still apply, so a prompt that is literally update runs fenced, with a token-less gh, not as you.
Belt and braces, because the failure was silent: omp, claude and codex are symlinks to their launchers
(~/.local/libexec/devbox-agent/<agent> on the devbox, ~/.local/libexec/devbox-agent/launchers/<agent> on the
laptop), never files named after the tool. An argv shape the passthrough does not recognise therefore hits omp's own
refusal to replace a script behind a symlink — a one-line error — instead of a release binary landing on top of the
launcher, which leaves agent sessions on your ~/.gitconfig, with SSH remotes and your keys. ./bin/devbox doctor
checks, on either side, that the symlinks are still symlinks.
- Author: the identity's App bot (
<app-slug>[bot]), since the App's token is what pushes and the author is visibly not you. - Unsigned:
commit.gpgsign = false,tag.gpgsign = false— keys are yours, out of an agent's reach. - HTTPS rewrite: one
[url "https://<host>/"]block per forge host any identity names, coveringgit@<host>:, the user-less<host>:form an ssh config withUser gitallows,ssh://git@<host>/, and (ongithub.com) thegh:shorthand — every remote on that host goes over HTTPS however cloned, whichever identity it was cloned with. No alias host to cover: remotes are always plain. - Credential helper:
[credential] helper =clears inherited helpers (blockingosxkeychainor yourghlogin), then one[credential "https://<host>"] helper = !devbox-git-credential, useHttpPath = trueper forge host (!runs it as a command on the launcher's PATH; a bare name would meangit credential-<name>). A host no identity'shostfield names gets no helper and fails outright (GIT_TERMINAL_PROMPT=0: immediate, not hung). - No prompts:
credential.interactive = falseand an emptycore.askPass. When the helper has no answer git fails instead of asking an askpass program — in an IDE terminal, one that answers with your own login — and never falls back toSSH_ASKPASS. includeIf gitdir:<dir>/— one per non-default identity that sets its ownagent_name/agent_email, pulling inagent-<slug>.gitconfig, resettinguser.name/user.emailto that identity's bot author — the same bot whose App installation token, ifappis configured, pushes it. An identity that leavesagent_name/agent_emailunset simply inherits the default author and gets no include.- Self-contained: excludes
~/.gitconfig. Both files carryinsteadOfrewrites for the same prefixes and git keeps the first read on a length tie, so including~/.gitconfigwould let its SSH rewrite beat the HTTPS one. - Rendered, not hand-edited: the static shape is
home/.config/devbox/git/agent.gitconfig.tpl;devbox-identities render agent-gitconfigsubstitutes the registry-derived blocks above for its@DEFAULT_AUTHOR@/@URL_REWRITES@/@INCLUDES@markers.container/bootstrap.shinstalls the result, plus oneagent-<slug>.gitconfigper identity that claims adir— every one of them, including those inheriting the default author, because git applies every matchingincludeIfand a tree nested inside another would otherwise keep the outer identity's author — and deletes any left over from a renamed or dropped identity.
Configured with useHttpPath: requests name the repository. Each request is answered from the identities that could
serve the request's host — the one owning the working directory first, then the rest in config order, so two accounts
with two Apps on the same host stay apart:
- For each candidate identity with
appcredentials (app-id+app.pem) at that path: sign a JWT (RS256,openssl; handed tocurlon stdin, never on its command line, which any local user can read), callGET /repos/{owner}/{repo}/installationagainst that identity's API (https://api.github.com, orhttps://<host>/api/v3for a GitHub Enterprisehost).200→ mint an installation token (POST /app/installations/{id}/access_tokens,repositories:[repo], one hour) and use it.404→ try the next candidate identity; any other status, or a failed mint, → hard failure, never a silent PAT downgrade. - Otherwise, the read-only fine-grained PAT of the identity the working directory belongs to —
devbox-gh-token, the same ruleghand git'sincludeIfuse. A clone or fetch succeeds, a push is refused by GitHub.
Any failure past the host check also prints quit=1: git otherwise reads a failed helper as "no answer" and asks the
next source, an askpass program. A failure therefore ends the operation, with the helper's one-line reason. A failed App
lookup or mint is never cached, and devbox-git-credential token exits non-zero on it, so the gh shim stops there
instead of falling back to the PAT. Only a definitive "App not installed" (every candidate 404) falls back.
store and erase are accepted and ignored. Three subcommands inspect or reset it:
| Command | Prints |
|---|---|
devbox-git-credential explain owner/repo [dir] |
Which path a request would take — app:<slug>:<installation-id> or pat:<slug> — without minting anything |
devbox-git-credential token owner/repo [dir] |
Just the App token, or nothing when no App covers the repository, and exits 1 when the lookup or mint fails: the gh shim's way to act as the same bot in an agent session (Secrets) |
devbox-git-credential forget [owner/repo] |
The cache entries it dropped — every identity's for that repository, or all of them without one; run after an App's permissions change (Secrets) |
Minting takes two API round trips (~0.75 s), so the App answer is cached per repository and per working directory's
identity: a token for 30 of its 60 minutes (whoever receives it keeps at least half an hour — gh run watch included),
"no App installed" for 5 minutes, so installing the App on a repository takes effect within that; a failure is never
cached. The cache is devbox-agent-<uid>/ under $XDG_RUNTIME_DIR, else /dev/shm (the container's tmpfs), else
$TMPDIR (the laptop) — mode 700, files 600, never under $HOME, which is the bind mount and gets backed up; a
directory not owned by you there disables caching rather than trusting it. devbox-git-credential forget forces a fresh
mint. The PAT path was never slow and is not cached.
An App is scoped per repository by its installation — no allowlist; installing it is all the configuration. A repo without the App gets the PAT, which is read-only (Secrets): agents can clone it, not push to it. A host nothing in the registry names gets no credential at all.
GIT_SSH_COMMAND points at devbox-git-no-ssh, printing a one-line explanation and exiting 255 (ssh's own "could not
connect") for any uncovered remote. Set in the environment, not core.sshCommand, so a repository-local override
can't reach past it — keeping an agent's git off your SSH keys and any forwarded agent, whatever the remote says.
Agent commits are unsigned — commit.gpgsign = false in agent.gitconfig, by design: the signing keys are yours.
Your manual commits are signed with gpg.format = ssh — on the laptop through 1Password's signer
(gpg.ssh.program = /Applications/1Password.app/Contents/MacOS/op-ssh-sign), on the devbox (ssh -A devbox) against
the forwarded 1Password agent:
user.signingkey = ~/.ssh/signing_personal.pub # or signing_work.pub under ~/projects/work/
commit.gpgsign = true
tag.gpgsign = true
gpg.ssh.allowedSignersFile = ~/.ssh/allowed_signers
The signing key is separate from the authentication key (id_*.pub) — GitHub registers both separately, one per
account; signing with it verifies locally but shows Unverified. signing_pubkey in ~/.config/devbox/identities.conf
is the public key GitHub lists under SSH signing keys — git config user.signingkey prints it on the laptop.
ssh-keygen -Y sign takes a public key file and signs through SSH_AUTH_SOCK — no private key on disk needed.
1Password asks the first time your terminal app uses the key, then remembers until it locks (its default). Without a
forwarded agent (ssh devbox, a herdr pane, ./bin/devbox shell), a manual commit fails to sign — by design.
git log --show-signature -1 # Good "git" signature with ED25519 key
gh api repos/<owner>/<repo>/commits/<sha> --jq .commit.verification # verified: true./bin/devbox agent install installs the identical mechanism on the laptop, from the home/ templates the devbox
bootstraps from:
./bin/devbox agent install| Destination | Installed |
|---|---|
~/.local/libexec/devbox-agent |
agent-launch, omp-launcher, claude-launcher, codex-launcher, the gh shim, fenced/git (the git shim), devbox-git-credential, devbox-git-no-ssh |
~/.local/bin |
devbox-gh-token, wt-herdr (wt herdr <branch>, Toolchain) |
~/.local/libexec |
devbox-identities |
~/.local/libexec/devbox-agent/launchers |
omp, claude and codex symlinks to their launchers (the pre-Claude ~/.local/bin/omp symlink is removed once omp resolves through the new directory — until then that link is what keeps omp fenced) |
~/.config/devbox/git/ |
agent*.gitconfig, rendered from the registry; every file is regenerated each run and the directory is locked read-only afterwards |
~/.config/devbox/identities.conf |
Never written — the installer names the cp command when it is absent (the example validates, so seeding it would author agent commits as your-agent) |
~/.config/devbox/secrets.env |
Created from the example if absent and never overwritten either |
~/.omp/agent/config.yml, ~/.claude/settings.json |
The agent guardrail presets: OMP's seeded only when absent, Claude Code's merged in with jq only when it holds no permissions.deny (Toolchain) |
~/.config/devbox/agent-context.md, ~/.agents/skills/devbox-runtime, ~/.claude/CLAUDE.md |
The agent context: the laptop template and the devbox-runtime skill (linked from ~/.claude/skills), regenerated each run, plus one import line appended to CLAUDE.md when missing (Toolchain) |
~/.codex/rules/devbox.rules, ~/.codex/AGENTS.md |
The Codex guardrail (Toolchain), a file of its own rewritten each run; and a copy of ~/.claude/CLAUDE.md with its imports expanded, the agent context included, rewritten each run — a file without its marker comment is yours and doctor laptop reports it |
The installer reads or edits nothing of yours in either file. It does not touch ~/.ssh/config or ~/.gitconfig —
on the laptop they are yours (below); bootstrap renders them on the devbox because nothing there is meant to be
hand-edited. Yours to write by hand, or to have rendered: a laptop set up with
rozsival/dotfiles gets both from dot identities, which calls the same
devbox-identities render … functions shown below — there, edit identities.conf and re-run it rather than editing the
output.
On the laptop the launchers need their own directory, first on your PATH, holding nothing but the three symlinks:
~/.local/bin cannot carry them, because Claude's native install owns ~/.local/bin/claude and re-points it on every
update, and Codex's installer does the same to ~/.local/bin/codex. Add, as the last line of ~/.zshrc/~/.bashrc
(after anything that prepends ~/.local/bin; dotfiles' env.sh already does this):
export PATH="$HOME/.local/libexec/devbox-agent/launchers:$PATH"Only a launcher's own PATH puts the libexec directory itself first — an ordinary shell or IDE never resolves the gh
shim, so your gh keeps its OAuth login. Whatever else resolves omp/claude/codex is "the real" one; the
installer reports which, whether each name resolves to its launcher, and prints the line above as a manual step until
it does. An agent that is not installed is fine — its launcher waits for it, and until then prints how to install it
(OMP's points the devbox at ./bin/devbox bootstrap, the laptop at the omp.sh installer; Codex's names its
standalone installer).
Printed by the installer: fill in each identity's block in ~/.config/devbox/identities.conf (at minimum
name/email, plus agent_name/agent_email on the default identity — see The identity
registry), a GH_TOKEN_<SLUG> per identity in ~/.config/devbox/secrets.env, and any
configured app directory's GitHub App credentials. See Secrets. ./bin/devbox doctor laptop then checks
this with the rest of the laptop side — keys, ~/.ssh/config, signing, tokens, connections (CLI
Reference).
Not installed by this repo either — devbox-identities render ssh-config prints the forge part (the Host/Match
blocks below plus a Host * with ServerAliveInterval), to copy in by hand or Include; the 1Password IdentityAgent
and the workstation/devbox blocks (Installation) are yours to add.
devbox doctor laptop checks the result, not what produced it. One plain Host <host> block per forge,
one Match host <host> tagged <slug> per identity whose key differs from the plain one, IdentityAgent on Host *
pointing at 1Password:
Host *
IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"
Host github.com
User git
IdentitiesOnly yes
Match host github.com tagged work
IdentityFile ~/.ssh/id_work.pub
Match host github.com !tagged work
IdentityFile ~/.ssh/id_personal.pub
Why tags rather than ssh -i: ssh tries the keys the agent lists in the agent's order, not the order given on the
command line, so ssh -i id_work.pub still answers as whichever account the forwarded agent offers first — measured,
not theoretical. A Match … tagged block is the only thing that overrides it.
The laptop side of the manual identity isn't installed by this repo either — it's your own ~/.gitconfig — but
devbox doctor laptop holds it to the same layout the devbox bootstraps: a base [user] that is the default
identity's, since every repository no include claims commits as it, one includeIf "gitdir:…" per tree (author and
signing key only — the SSH key follows the repository's owner, not the tree), and one set of four
includeIf "hasconfig:remote.*.url:…" per identity with orgs (author, signing key, and the ssh tag):
gpg.format = ssh
gpg.ssh.program = /Applications/1Password.app/Contents/MacOS/op-ssh-sign
commit.gpgsign = true
user.name = Your Name
user.email = you@personal.example
user.signingkey = ~/.ssh/signing_personal.pub
gpg.ssh.allowedSignersFile = ~/.ssh/allowed_signers
includeIf "gitdir:~/projects/work/" → user-work.gitconfig ([user] only)
includeIf "hasconfig:remote.*.url:git@github.com:your-org/**" → org-work.gitconfig
includeIf "hasconfig:remote.*.url:git@github.com:/your-org/**" → org-work.gitconfig
includeIf "hasconfig:remote.*.url:ssh://git@github.com/your-org/**" → org-work.gitconfig
includeIf "hasconfig:remote.*.url:https://github.com/your-org/**" → org-work.gitconfig
devbox-identities org-urls work prints the four patterns for an identity's orgs;
devbox-identities render org-gitconfig work prints the file they point at — any path; the devbox keeps them in
~/.config/devbox/git/, dotfiles in ~/.config/git/identities/, both named org-<slug>.gitconfig:
[user]
name = Your Name
email = you@work.example.com
signingkey = ~/.ssh/signing_work.pub
[core]
sshCommand = ssh -P work
[core] sshCommand is only in the org file, never the gitdir: one: it is what makes the ssh tag follow the
repository's owner, independent of which tree it was cloned into. devbox-identities render user-gitconfig work prints
the gitdir: file the same way — [user] only, no sshCommand, since a personal repository cloned into a work tree
still has to push with your own key.
allowed_signers needs one line per identity (<email> <key type> <key>) so git log --show-signature verifies all of
them — devbox-identities render allowed-signers builds it from whichever signing_<slug>.pub files exist on disk.
Both machines hold the same identities.conf. ./bin/devbox sync identities [ssh-host] copies the laptop's copy to the
devbox (keeping one identities.conf.bak there), validates it locally with devbox-identities check first so a broken
file never lands, then re-runs container/bootstrap.sh so ~/.ssh/config, ~/.gitconfig's user-*/org-* includes,
the agent gitconfigs and allowed_signers catch up — the same regeneration ./bin/devbox bootstrap does on its own,
and just as idempotent. The laptop's own ~/.ssh/config and ~/.gitconfig follow by hand, or by dot identities on a
dotfiles laptop; devbox doctor laptop is what notices drift.
| Check | Command | Expected |
|---|---|---|
| Which credential path a repo would take, without minting a token | devbox-git-credential explain <owner>/<repo> |
app:<slug>:<installation-id> or pat:<slug> |
| Who owns a directory | devbox-identities for ~/projects/work/<repo> |
— |
| Every resolved field for an identity | devbox-identities show work |
— |
| Inside an agent session: who git thinks it is | git var GIT_AUTHOR_IDENT |
your-agent <your-agent@users.noreply.github.com> ... |
| Inside an agent session: HTTPS and the helper are wired | git config --get credential.https://github.com.helper |
!devbox-git-credential |
| Inside an agent session: the request really goes over HTTPS | GIT_TRACE=1 git ls-remote https://github.com/<owner>/<repo> 2>&1 | grep -i http |
— |
| A second identity's directory picks its own author | cd ~/projects/work/<repo> && git var GIT_AUTHOR_IDENT |
your-app[bot] <...> |
| The fence: any non-GitHub SSH remote refuses | git ls-remote git@gitlab.com:foo/bar |
devbox: ssh remotes are disabled in agent sessions... |
| Manual identity, forwarded agent required | ssh -A devbox, then ssh -T git@github.com |
Hi <user>! — default identity's key |
| Manual identity, second key | ssh -P work -T git@github.com |
Hi <user>! — work identity's key |
Yes. The default identity catches every tree no other dir overrides; the ~/projects/<slug>/ layout is
organisational, not functional.
No — hasconfig:remote.*.url: matches the remote's URL text, not a directory, so the org's identity (author, signing
key, ssh tag) applies wherever the clone lives. Move it for tidiness if you like; nothing to fix. Only the dir-scoped
fallback — an identity's own non-org repositories inside its tree — cares where a repo sits.
ssh picks a key by host, so before tags existed, a second identity needed a fake Host <slug>.<host> block and a
git@<slug>.<host>: URL in every remote and every clone command just to give ssh something to key off. Two things
removed the need: hasconfig:remote.*.url: matches the remote itself — case-sensitively, as text, against
git@<host>:<org>/**, ssh://git@<host>/<org>/** and https://<host>/<org>/** (orgs must be spelled exactly as
GitHub spells the owner) — and it already holds on the very first git clone, since clone writes the remote before it
fetches; no alias was ever needed to make that first clone land right. The ssh tag (ssh -P <slug>, set by
org-<slug>.gitconfig's core.sshCommand) replaced the alias host for picking the key: a
Match host <host> tagged <slug> block, not ssh -i — ssh offers keys in the order the agent lists them, not the
order given on the command line, so ssh -i id_work.pub still answered as whichever account the forwarded agent offered
first, measured on this repo before tags existed. Old clones left on a git@<slug>.<host>: remote resolve nothing now
(devbox-identities alias-remotes lists them; devbox doctor laptop and bootstrap print the git remote set-url
commands to fix each one).
Fixed in the launcher, and worth recognising: before the update passthrough existed, the updater resolved omp on the
launcher's own PATH and wrote the release binary straight over the launcher script, so later sessions read
~/.gitconfig — SSH remotes, your keys, 1Password prompting. Repair is ./bin/devbox agent install on the laptop,
./bin/devbox bootstrap on the devbox; both are idempotent and the update itself is not lost (re-run omp update).
Recognition cue: ./bin/devbox doctor laptop reports the installed launcher no longer matching the repo template — the
omp symlink stays intact, it is the file behind it that became a ~180 MB binary. Inside a session,
echo $GIT_CONFIG_GLOBAL printing nothing says the same thing.
Yes. All launchers source the same agent-launch, so they read the same agent.gitconfig, the same credential helper
and the same gh shim: the identity follows the tree a repository sits in, never the agent. Claude Code additionally
adds its own Co-Authored-By trailer to commit messages (its attribution setting) — text in the message, not the
author.
command -v claude prints ~/.local/bin/claude: the launchers directory is not ahead of it on the PATH. Add the
export PATH=…/launchers:$PATH line from Laptop install after whatever puts ~/.local/bin first,
then open a new shell. A claude started from an IDE that ignores your shell PATH bypasses the launcher the same way;
start agent sessions from a terminal. The Claude desktop app is the exception: its sessions get the fence from a
SessionStart hook instead (Claude desktop app).
Different failure from the one above, and the fence was working: HTTPS remote, per-operation token, unsigned commit —
only the author was wrong. The [user] section of the installed ~/.config/devbox/git/agent.gitconfig had been
rewritten, which is what a git config --global user.name … inside a session does: GIT_CONFIG_GLOBAL points at that
file. On this laptop the caller was not an agent at all but ~/.extra, sourced by ~/.bash_profile, so any login bash
a session started did it. Delete those two lines from the dotfile. The directory is mode 500 now, so the same call fails
with could not lock config file; repair a drifted copy with ./bin/devbox agent install (laptop) or
./bin/devbox bootstrap (devbox). Both sides of doctor compare the two files against the templates and check the
mode. Commits already made are only fixable by rewriting history, and --reset-author is the wrong tool: it takes the
author from the shell doing the rewrite, so from your own terminal it stamps you again. Name the author instead, per
commit to rewrite, and leave your own commits alone: git rebase -i <base> from your own terminal with
exec git commit --amend --no-edit --no-gpg-sign --author='your-agent <your-agent@users.noreply.github.com>' after each
offending pick. --no-gpg-sign matters: your commit.gpgsign = true would otherwise sign the bot-authored commits with
your key. Commits of yours that the rebase re-creates are re-signed automatically (1Password asks once per terminal
app, then remembers until it locks). Then force-push, after checking nobody else has pulled the branch.
No private key to sign with in an agent session, and its git never touches a forwarded agent — GIT_SSH_COMMAND fences
off SSH, with no HTTPS equivalent of ssh-keygen -Y sign. agent.gitconfig sets commit.gpgsign = false rather than
fail. Provenance: author identity, and for App-backed pushes, only the App's token could have pushed it — not a
signature.
A private key there is ambient push authority for every agent, present or not. Public keys, plus an agent forwarded
only for one ssh -A connection, keep that authority with you. bootstrap deletes any earlier devbox-generated
private key, printing its fingerprint for revoking on GitHub. See Security Model.
Either the connection wasn't -A forwarded (ssh devbox instead of ssh -A devbox), or the laptop's key isn't
registered as an Authentication key on the GitHub account. Reconnect with -A and check ssh -T git@github.com.
For a manual commit: the laptop key is missing as a Signing key, or the commit email isn't attached to the account. For an agent commit: expected — never signed.
The same way git picks an identity: by directory. GH_TOKEN_<SLUG> for each identity lives in
~/.config/devbox/secrets.env; the gh shim (~/.local/libexec/devbox-agent/gh) resolves one per invocation from the
directory (devbox-gh-token --account reports which). See Secrets.
No. It gets the identity's PAT, which is read-only by design, so GitHub refuses the push. Install the App on the
repository — devbox-git-credential explain <owner>/<repo> then prints app:<slug>:<id>. Never give the PAT write
access: every agent could then push as you.
In an agent session, gh commands about one repository the identity's App is installed on use that App's installation
token — the one its git pushes with — so PRs, issues and comments carry the same author as the commits. Your own gh,
and account-wide agent commands (gh repo list, gh api user), keep the PAT. See
Secrets.
One [slug] block in ~/.config/devbox/identities.conf with its own app directory, a read-only GH_TOKEN_<SLUG> in
~/.config/devbox/secrets.env, the App's app-id + app.pem, and the
identity's two public keys, already on GitHub. Apply with ./bin/devbox sync identities from the laptop, or
./bin/devbox bootstrap on the devbox alone — no code change, nowhere. See The identity
registry.
Yes — the way to give an organization of your own its own token, since a fine-grained PAT has exactly one resource owner
(your user or one org). Copy the default block under a new slug with its own dir and orgs naming that org, the
same pubkey/signing_pubkey as the default (so it gets no tag — the key already matches the plain one), and copy
id_<default>.pub/signing_<default>.pub to the new slug's names on the laptop. A key of its own per org on the same
account works too: give the block its own pubkey/signing_pubkey and it gets a tag. Either way devbox doctor laptop
only checks that each connection authenticates with the key its pubkey names, not which account answers.
Neither is authoritative by itself; they're expected to agree. ./bin/devbox sync identities always copies laptop →
devbox (validating with devbox-identities check before it copies), because the laptop is where you hand-edit the file
and where 1Password holds the private keys it names. Editing the devbox's copy directly works too —
./bin/devbox bootstrap re-derives everything from whichever copy is on disk there — but the next sync identities
overwrites it with the laptop's, so a devbox-only edit should be mirrored back by hand or it will be lost on the next
sync.
Point both blocks' app field at the same directory. devbox-git-credential tries the working directory's own identity
first and then the rest in config order, so whichever one the App is actually installed for answers
GET /repos/{owner}/{repo}/installation with 200; the other falls through. One App installed on repositories from two
orgs works the same way as two Apps, at the cost of both identities sharing one app.pem to protect.
Its git is still fenced to HTTPS — same as anywhere else. Nothing else is: while that connection lasts, any process in
the devbox, that session's shell commands included, can reach the forwarded agent socket with a raw ssh call. See
Security Model.