Credential proxies¶
A hardened sandbox denies ~/.ssh, ~/.config/gh, and every other credential
store — which also strips the agent of git push, gh pr create, and the
issue tracker. The credential proxies give those workflows back without
putting a secret inside the wall: the agent describes a semantic operation
("push my branch", "comment on this PR"), and the agentd daemon builds the
actual git invocation or API call on the host, where the credentials live.
Semantic proxies have no passthrough flag or raw-query escape hatch. A named
HTTP proxy additionally supports arbitrary requests within an operator-pinned
base URL. Every gate is enforced daemon-side.
Six proxy families exist, as subcommands of a top-level command:
tclaude proxy git # fetch, pull, push through the daemon
tclaude proxy github # PRs, issues, and Actions runs (alias: gh)
tclaude proxy gitlab # merge requests, issues, pipelines and jobs (alias: gl)
tclaude proxy linear # Linear issues, bounded by a team allow-list
tclaude proxy awb # AWB issues, bounded by a workspace allow-list
tclaude proxy http # HTTP(S) requests through a named service instance
None of their permissions are granted by default, and none are implied by
group ownership. Gated verbs support --ask-human <timeout>, except proxy git remotes (capped at
300 seconds): on a permission denial, the operator gets a popup approval, and a
timeout counts as a deny.
The command only appears when configured¶
tclaude proxy is conditionally registered. On a host where no proxy is
configured, it is an unknown command and does not appear in tclaude --help —
by design, so unconfigured operators do not advertise a capability their
agents cannot use. The command registers when any proxy family is configured:
agent.git_proxy.allowed_remotesis non-empty (Git, GitHub and GitLab), oragent.linear_proxynames an allow-list, a key file or a workspace route, oragent.awb_proxy.urlis set, oragent.http_proxieshas at least one named instance, or- the caller is a managed agent and a capability probe of agentd's
GET /v1/inforeports proxy support (daemons predating that projection keep the command visible).
The permission catalog follows the same per-family answer: a host
advertises proxy.git.* / proxy.github.* / proxy.gitlab.*, proxy.linear.* and proxy.awb.*
only where that family could work, plus any family the calling agent holds a
scoped grant for. The two must agree — advertising a slug whose command is not
registered would let an operator grant a capability nothing can exercise.
One asymmetry is deliberate and worth knowing. The daemon also counts
LINEAR_API_KEY in its own environment as a configured Linear family, so a
managed agent (which reads the projection) gets the command from an
environment-only Linear setup. A plain host shell does not: it answers from the
config file alone, because probing the daemon on every tclaude invocation
would cost a round trip on every command. An operator running an
environment-only Linear proxy who wants tclaude proxy in their own shell
should give agent.linear_proxy an api_key_file (or an allowed_teams list)
rather than relying on the variable.
Visibility is not enforcement. The full registry still backs validation and stored-grant resolution, so hiding a slug never withdraws a grant made under it.
A managed agent is recognised by any of TCLAUDE_AGENTD_SOCKET,
CODEX_PERMISSION_PROFILE=tclaude-agent, or TCLAUDE_AGENT_HINT=1 in its
environment. Only the last is carried by every managed launch: the socket is
pinned for sandboxed agents alone, so an unsandboxed managed pane has the hint
and nothing else.
The local config read cannot stand in for that test: a sandbox that denies
~/.tclaude/data by mounting it empty makes an enabled config look exactly
like an absent one, with no error to distinguish them.
If an agent reports that tclaude proxy does not exist, that is the symptom
of an operator who has not opted in — not a broken install.
Git proxy¶
tclaude proxy git remotes # list remotes with a per-remote verdict
tclaude proxy git ls-remote --remote origin
tclaude proxy git fetch --remote origin
tclaude proxy git pull # daemon fetches, then fast-forwards locally
tclaude proxy git push --remote origin --branch my-branch
pull is deliberately split: the daemon only fetches, and the fast-forward
happens locally, so the daemon never merges or checks out in the agent's
tree. push supports force only as --force-with-lease, and only when the
operator config sets allow_force_push; plain --force is never available.
Pushes to protected_refs are refused.
Permissions, both scopable to a remote dimension:
proxy.git.read—remotes,ls-remote,fetch,pull.proxy.git.push—push.
Operator configuration¶
The agent.git_proxy block lives in ~/.tclaude/data/config.json (private
daemon state; migrated automatically from the legacy ~/.tclaude/config.json).
Edit it there or in the dashboard's
Config › Git & forges:
allowed_remotes— the operator-global allow-list ofhost/owner[/repo]patterns, matched segment-wise (*matches one segment, and a shorter pattern is a prefix match). SSH and HTTPS URLs normalize to the same key. Authorization is the per-agentremote-scoped grant, or this list, or both must match when both exist; there is deliberately no "allow everything" setting. A non-empty list is also what registers the command, and it bounds the dashboard's Branch-column PR/branch links, which spend the sameghcredentials.protected_refs— default["main", "master"]; an explicit[]disables.allow_force_push— default false.ssh_key— pin one key; empty uses the daemon's ambient ssh-agent.github_token_file— the GitHub token source (GitHub proxy only); empty falls back togh auth token, and that is the entire token chain.gitlab_hosts— a map from a remote host to the base URL of the GitLab instance that serves it,{"gitlab.example.com": "https://gitlab.example.com:8929"}. It does two jobs: it is how the daemon recognises a remote as a GitLab project at all (a self-hosted instance cannot be told apart from any other git server by its name), and it is where the web/API root lives, which may differ from the SSH host in scheme and port.gitlab.comneeds no entry while this map is empty. Once you list any instance, listgitlab.comtoo if you use it, because the onegitlab_token_fileis sent only to listed instances, never to a third party you did not name. The footer's Open MRs indicator always needs an entry. The base must be anhttpsorigin,https://host[:port]with no path; the GitLab token is only ever sent to it. An instance served under a path (a GitLab "relative URL root") is not supported, and its entry is ignored with a warning. It is also the one way a remote URL may name a port: anhttpsremote whose scheme, host and port are exactly a base here is accepted (see GitLab proxy).gitlab_token_file— the GitLab token source: a personal or project access token with theapiscope. The GitLab verbs send it to the API, and git uses it forhttpspushes and fetches to a configured instance. There is no CLI fallback; with no file configured every GitLab verb refuses and says so. A fine-grained token limited to some projects works too, for those projects. It may not list the whole instance, so the footer's Open MRs all reads everyone's merge requests project by project instead: the projects your agents work in, those of your own open merge requests, and everyallowed_remotesentry that names one exact project on the instance (no*). A project in none of those is not shown.
~/ expands in these values; shell variables do not.
GitHub proxy¶
tclaude proxy github pr create --title "Fix the flake" --body-file pr.md
tclaude proxy github pr view 2277
# other pr verbs: ls, checks, comments, ready, comment, edit, merge
# issue verbs: ls, view, comment
# run verbs: ls, log-failed, artifacts, download
Operations are restricted to the repository that the agent's own recorded launch remote resolves to — and only when that remote is allowed. The token travels as an Authorization header to the API, never through child process argv or environment.
Permissions:
proxy.github.read—pr ls/view/checks/comments,issue ls/view, and therunverbs.run downloaddoes write, but only into.tclaude-artifacts/inside the agent's own work tree (a computed destination, capped at 512 MiB compressed / 2 GiB unpacked per download, with at most 3 run directories kept).proxy.github.write—pr create/edit/comment/ready,issue comment. Does not imply merge.proxy.github.merge—pr mergeonly, split from write on purpose: an operator can let agents open and discuss PRs while keeping the merge button human. GitHub's own branch protection still applies;protected_refsdoes not (it bounds direct pushes only).
GitLab proxy¶
tclaude proxy gitlab mr create --title "Fix the flake" --body-file mr.md
tclaude proxy gitlab mr view 157
# other mr verbs: ls, checks, comments, ready, comment, edit, merge
# issue verbs: ls, view, comment
# pipeline verbs: ls
# job verbs: log-failed <pipeline-id>, artifacts <job-id>, download <job-id>
The same contract as the GitHub proxy against a GitLab instance. Operations
are restricted to the project that the agent's own recorded launch remote
resolves to, and only when that remote is allowed and its host is a
configured instance (gitlab_hosts, or gitlab.com while no instance is
listed). The project is the
full namespace path, group/subgroup/project, exactly as the allow-list
admitted it; a nested path is ordinary on GitLab and is never re-derived
from its first and last segments. The token travels as an
Authorization: Bearer header, never through argv or a child's environment.
That is the standard header, so a reverse proxy in front of the instance
passes it through. The token is sent only to the instance's exact origin
(scheme, host and port): a redirect elsewhere, such as an artifact download
handed to object storage, is followed without it, and a redirect to plain
http is refused.
To authorise some projects and not others, write them out:
"agent": {
"git_proxy": {
"allowed_remotes": [
"gitlab.example.com/acme/player",
"gitlab.example.com/acme/player-dashboard",
"gitlab.example.com/acme/tools/*"
],
"gitlab_hosts": {"gitlab.example.com": "https://gitlab.example.com:8929"},
"gitlab_token_file": "~/.config/tclaude/gitlab-token"
}
}
A remote-scoped grant (--scope remote=gitlab.example.com/acme/*) narrows
this further per agent, as it does for GitHub.
Where the two forges differ, the GitLab verbs follow GitLab:
- A merge request's number is its iid (
!157), which is what every verb takes and whatmr lsreports asnumber. - A draft is a title prefix (
Draft:), not a flag.mr create --draftadds it andmr readyremoves it. mr checksreports the head pipeline and its jobs rather than a check rollup; the pipelineidis whatjob log-failedtakes, and a jobidis whatjob artifactsandjob downloadtake.job log-failedprints the whole trace of each failed job, tailed, since GitLab has no per-step log. Jobs allowed to fail are included and labelled.mr merge --methodoffersmergeandsquash; a rebase is a separate GitLab operation the proxy does not perform.- Artifacts belong to a job and land in
.tclaude-artifacts/job-<id>/, sharing the three-directory cap with GitHub'srun-<id>/.
Permissions, all scopable to a remote dimension:
proxy.gitlab.read—mr ls/view/checks/comments,issue ls/view,pipeline ls, and thejobverbs (job downloadwrites into.tclaude-artifacts/under the same bounds asrun download).proxy.gitlab.write—mr create/edit/comment/ready,issue comment. Does not imply merge.proxy.gitlab.merge—mr mergeonly. GitLab's own protected-branch rules and approval requirements still apply;protected_refsdoes not.
An agent's remote can take either form GitLab's clone button offers:
- SSH,
git@gitlab.example.com:acme/app.git. Pushes and fetches use the daemon's SSH key (ssh_key, or its ssh-agent). https, with the instance's port when it has one:https://gitlab.example.com:8929/acme/app.git. The git proxy otherwise refuses a remote URL that names a port, because the allow-list cannot express one. It accepts this one because the scheme, host and port are exactly thegitlab_hostsbase, a destination the operator has already written down. Another port on the same host, or a port on anssh://URL, is still refused.
Over https, git asks a credential helper for a password. For each
configured instance the daemon answers with gitlab_token_file, and that is
the only answer for the instance's exact origin (scheme, host and port). The
operator's own credential helpers are not asked for it, and are never told to
erase what they store for it when GitLab rejects the token. Every other host
or port keeps the operator's helpers, and never sees the token. The token
stays off the command line and out of git's environment: the helper reads
the file when git asks. With no token file configured, the operator's helper
answers for the instance as before. With one configured but missing or empty,
the push fails rather than falling back.
A merge request opened through the proxy, or presented with
tclaude agent present-pr <merge-request URL>, shows on the dashboard like a
pull request: its state and head-pipeline jobs are read through the same
token, under the same allow-list. With gitlab_hosts and a token configured,
the dashboard footer also lists the token user's open merge requests on every
configured instance; see Open MRs.
Linear proxy¶
tclaude proxy linear whoami # key identity + reachable teams
tclaude proxy linear issue view TCL-123
# other issue verbs: ls, search, comments, comment, create, update, link
There is no CLI tool underneath: the daemon speaks Linear GraphQL directly, and every GraphQL document is a compile-time constant with caller values carried only in variables. Unlike git, Linear has no filesystem anchor — no remote to resolve — so the team allow-list is the entire scope gate, mandatory and fail-closed.
Permissions, scoped on the linear_team dimension (for example
--scope linear_team=TCL):
proxy.linear.readproxy.linear.write— additionally requires the operator configagent.linear_proxy.allow_write.
Scoped grants intersect with the operator's allowed_teams list when one
exists; an unscoped grant is refused outright when the operator has no list.
Read and write scopes are independent.
The agent.linear_proxy block in ~/.tclaude/data/config.json:
allowed_teams— team keys, case-insensitive, no wildcard by design.api_key_file— the default key; empty falls back toLINEAR_API_KEYin agentd's environment, and with neither the proxy refuses.workspaces— routes named teams to a different key, because one Linear personal key is scoped to one workspace; each workspace entry requires its ownapi_key_file, with no environment fallback.
AWB proxy¶
tclaude proxy awb whoami # server, account, reachable workspaces
tclaude proxy awb ready --compact # the primary entry point
tclaude proxy awb claim awb-a3f9c1
tclaude proxy awb make-ready awb-a3f9c1
tclaude proxy awb update awb-a3f9c1 --commit-hash 01234567
tclaude proxy awb update awb-a3f9c1 --pull-request-url https://github.com/acme/repo/pull/42
tclaude proxy awb comment add awb-a3f9c1 --key agent7-findings-v1 --body-file findings.md
# other verbs: show, list, blocked, search, create, update, close, reopen,
# release, delete, label add|rm, dep add|rm|tree,
# comment list, activity, attach add|list|show|get|delete
AWB — Agent Work Board — is an agent-first issue tracker with an HTTP API. As with Linear there is no CLI tool underneath: the daemon speaks AWB's REST API directly, every path is assembled from compile-time constants plus a validated issue reference, and every caller value travels as a query parameter or a marshalled JSON field. And as with Linear there is no filesystem anchor, so the workspace allow-list is the entire scope gate, checked once on the reference the caller supplied and again on the workspace AWB reports for the issue it returned.
The verbs and flags mirror awb's own, minus five that name a local database or
terminal rather than the data: --db, --attachments, --no-context,
--color, --no-color. Three differences are worth knowing:
- A bare hash is refused.
awbacceptsa3f9c1; the proxy requiresawb-a3f9c1(a hash prefix is fine), because a reference carrying no workspace key could only be gated after the issue had been fetched. - Listings are bounded.
awbreturns every row by default; the proxy defaults to 50, capped at 500, because the rows land in an agent's context.comment listandactivityare bounded the same way, and additionally cap--offset. - Claims use the operator's user.
claim --asis absent because proxy claims always belong to the configured AWB account.
Comments are an append-only timeline shared with AWB's change records.
Each new comment requires a caller-chosen --key; retrying the same key and
body returns the original entry instead of appending a duplicate.
All proxy callers share the operator's AWB identity, and therefore share its
per-issue key namespace. Include an agent- or task-specific component in the
key. Reusing a key with a different body returns a conflict.
activity reads the whole thing (--kind comment|change narrows it) and
comment list is the same read with the kind fixed. A close reason lives there
too: since AWB 0.6 close --reason records a typed comment rather than setting
a field on the issue, and the issue carries no close_reason at all.
Issues can carry a caller-owned JSON object through create --metadata and
update --metadata. Updates merge it at the top level, matching AWB's CLI and
API; metadata appears in JSON issue detail and is omitted from summaries and
compact output.
dep tree is pruned to the caller's workspaces: AWB follows children across
workspace boundaries by design, so a child outside the gate is dropped with its
subtree. whoami describes only the workspaces the caller may reach; one it may
not is reported as its key alone, which is what a refused agent needs in order
to ask for it and nothing more. Attachment content travels through the daemon in request and response
bodies rather than as a path it would read from the agent's work tree, which
caps it at 8 MiB either way.
Permissions, scoped on the awb_workspace dimension (for example
--scope awb_workspace=awb):
proxy.awb.read—whoami,show,list,ready,blocked,search,dep tree,comment list,activity,attach list/show/get.comment listandactivityare the reads that carry third-party prose into an agent's context: anyone with tracker access can write a comment.proxy.awb.write— everything that changes the tracker, including the harddelete(which additionally needs--force). Requires the operator configagent.awb_proxy.allow_write.
Scoped grants intersect with the operator's allowed_workspaces list when one
exists; an unscoped grant is refused outright when the operator has no list.
Read and write scopes are independent.
A workspace scope bounds what the agent reaches unattended. A workspace the
operator's allowed_workspaces list carries but the grant's scope does not can
still be reached for one request by retrying with --ask-human: the
operator gets the usual popup, naming the workspace, and an approval authorizes
that request alone — nothing is persisted, and the next call is gated afresh.
The refusal says so when this route is open. Three bounds keep it from becoming
a way to widen a grant:
- the operator's list is a hard ceiling, and a workspace outside it (or a host with no list at all) is refused with no popup, so an agent cannot pester the operator into authorizing something they excluded;
- one approval covers one workspace, so a request naming two out-of-scope workspaces is refused rather than approved by a popup that could only name one of them;
allow_writeis unaffected — the popup answers "may this agent touch that workspace", never "may agents write at all".
The agent.awb_proxy block in ~/.tclaude/data/config.json:
url— the AWB server's base URL. This is what registers the command; only http/https, and a URL carrying userinfo is refused rather than stripped.username— the account every proxied call authenticates as, and the identity AWB attributes writes to. It is also the AWB user everyclaimassigns and what--minefilters on. Empty suits a server whose database holds no user, which AWB treats as unauthenticated, butclaim, non-forcedrelease, and--minethen refuse because the proxy has no operator identity to use.password_file— empty falls back toAWB_PASSWORDin agentd's environment; with a username and neither, the proxy refuses rather than sending half a credential. The password is never a field ofconfig.jsonitself.allowed_workspaces— workspace keys, case-insensitive, no wildcard by design.allow_write— default false.ready_polling— optional map keyed by a unique process name. Each entry names aworkspaceand starts one serial daemon worker which immediately asks AWB for the first matching ready issue, claims it, and spawns an agent into the configured group and absolutecwd. The worker does not advance until that exact issue isclosed, even if the agent exits or the issue is released or reassigned. Configuration is read at agentd startup; restart agentd after changing it.
Each entry requires workspace, group, and an absolute cwd. Optional
labels are passed as repeated AWB label filters. interval defaults to
1m and paces every poll except one that releases the issue in flight:
once that issue closes, the worker asks for the next ready issue
immediately rather than waiting an interval. profile, sandbox_profile, harness, model, effort, and worktree are optional.
Non-empty fields in issue metadata override the corresponding pickup defaults,
for example "agent": {"harness": "claude", "model": "sonnet", "effort": "high"}.
A metadata harness pins that issue to one vendor, replacing the fallback chain.
Omitted or empty fields retain the configured defaults; unset model and effort
resolve through the spawn profile chain. Invalid agent settings stop pickup
and are reported for correction.
harness takes one name ("codex") or an ordered fallback chain
(["codex", "claude"]) — see "Usage ceilings on pickup" below for what the
chain does. skip_epics defaults to false; when true, the worker skips
epic issues in the ready queue and picks its first ready non-epic issue.
monitor_pr defaults to false; when true, the worker watches a GitHub pull
request recorded in the issue's pull_request_url through the configured
GitHub proxy. After the pull request is merged and the spawned agent exits or
becomes idle, the worker closes the AWB issue and advances to the next one.
This requires agent.git_proxy to be enabled, the PR repository to match
allowed_remotes, and a GitHub token available to agentd. The spawned agent's
brief tells it to record the PR URL on the issue; an unreachable or non-GitHub
URL is left alone and reported in the daemon log.
monitor_commit also defaults to false and is an alternative to
monitor_pr for workflows without pull requests. It watches the issue's
commit_hash and, after the spawned agent exits or becomes idle, checks
origin/main through a hardened, isolated fetch. The origin remote must
be allowed by agent.git_proxy.allowed_remotes. Without an origin remote,
this option has no effect and the worker logs a warning when it picks up an
issue. Once the recorded commit is an ancestor of origin/main, the worker
closes the issue and advances. This assumes the
recorded commit reaches main verbatim;
a commit rewritten by rebase or squash never satisfies the check. The
spawned agent's brief tells it to record the commit hash on the issue.
monitor_close also defaults to false. It instructs the spawned agent to
close its issue when done. Once the issue is closed and the agent is idle or
exited, the worker cleans up and advances. The three monitoring options are
mutually exclusive.
Whenever the worker closes an issue itself, it also clears up after that
pickup: the agent it spawned is retired and its pane soft-stopped, and with
worktree: true the linked worktree is removed. The branch is deleted only
when the worker can prove that the branch's current tip has landed — either
because the merged pull request it watched merged that exact commit into a
trunk, or because the tip is already contained in the main the process
monitors. An unproven branch is kept and the worktree directory is removed
without it, and even a proven branch is deleted with a compare-and-swap on
that commit, so a branch that gained work after the proof survives. An agent
that has gone back to work is left alone, agent and worktree both; the check
is taken again immediately before the retire commits, so a turn started while
the worker was still consulting git does not lose its agent. None of this
applies to an issue an operator closes by hand outside monitor_close mode.
Multiple processes may use the same workspace when every process has a
non-empty label filter and those configured label sets are disjoint. An
unfiltered process therefore must be the workspace's only process.
Polling additionally requires url, a non-empty username,
allow_write: true, and inclusion of the workspace in
allowed_workspaces. With worktree: true, the issue ID is used verbatim as
the branch name. Spawned agents receive workspace-scoped proxy.awb.read
and proxy.awb.write grants.
"ready_polling": {
"tcl-backend": {
"workspace": "tcl",
"labels": ["backend"],
"group": "builders",
"cwd": "/absolute/path/to/repo",
"interval": "1m",
"profile": "worker",
"sandbox_profile": "repo-write",
"harness": "codex",
"worktree": true,
"monitor_commit": true
},
"tcl-frontend": {
"workspace": "tcl",
"labels": ["frontend"],
"group": "builders",
"cwd": "/absolute/path/to/repo",
"monitor_pr": true
}
}
Usage ceilings on pickup¶
When the top-level ratelimit block is configured, a polling process checks
the usage of the harness it is about to spawn before it takes another issue,
and holds off while that harness is over the ceiling:
five_hour_percent_max_used governs the harness's short rolling window and
seven_day_percent_max_used its long one — Claude's 7-day buckets (including
the Sonnet bucket), Codex's weekly window, and GitHub Copilot's monthly
premium-request quota. Without the block, nothing is gated; this is the same
configuration tclaude task waits on, so one setting covers both.
The harness checked is the one the spawn would actually use: the process's
issue metadata agent.harness, then the process's harness, or whatever its profile, the group default profile, or the global
default profile resolves to. OpenCode runs against the operator's own provider
keys and has no account-wide window to read, so its processes are never held.
Gemini session logs do not provide captured account-quota windows either, so
Gemini processes are not held by this gate; check the CLI’s /model quota display.
A process can name several harnesses instead of one, as an ordered fallback chain:
"tcl-backend": {
"workspace": "tcl",
"group": "builders",
"cwd": "/absolute/path/to/repo",
"harness": ["codex", "claude"]
}
Each pickup takes the first entry still under its ceilings, so the process keeps working on the next vendor while the first one's window recovers, and only a chain whose every entry is spent holds the process. The hold then names the entry resetting soonest, because that is when the chain frees up again. Order is the preference: the chain is walked from the front on every pickup, so a recovered first choice is used again as soon as it is under its ceiling. An issue claimed before its spawn re-picks from the same chain on the freshest reading, but is never held — it is already assigned on the operator's account.
Note that a chain is only a usage fallback. The harness a spawn lands on
changes the vendor, model catalogue and sandbox posture of the agent that does
the work, so every entry should be one the process's issues can actually be
worked on; profile and sandbox_profile still apply to whichever entry is
chosen. Explicit pickup model and effort defaults also apply to every
chosen vendor, including a metadata harness override. Set compatible values,
omit them to use per-harness profile defaults, or override them together in
issue metadata; incompatible explicit values fail spawn validation.
While a process is held it reads the next ready issue and its metadata without
claiming it, and it resumes within one
interval of the offending window resetting. The hold is written to the daemon
log at info level and to the audit trail — verb awb.ready.ratelimited — once
per hold rather than once per poll, so a quiet process is explainable without
reading a usage graph. An issue already picked up is never abandoned to a
ceiling: the hold only decides whether to start something new.
Readings come from the same local caches the dashboard's usage readout uses, so
no network call is made to decide a hold, and a missing or stale reading lets
work proceed rather than stalling it. That matters most for Claude, whose
figures are refreshed by Claude Code's statusline callback while its sessions
run; an operator who wants the gate to hold across long idle stretches should
also enable usage.poll_anthropic_api.
AWB applies its own authorization underneath: the daemon's account works in the
workspaces it is a member of, and one it holds no access to answers 404. That
bounds the operator; the allow-list above bounds the agent.
Inspecting and resetting pickup processes¶
Because a process never advances past an issue that does not close, an issue
nobody finishes blocks its process indefinitely. tclaude pickup is the
operator's view of every process and the way to unblock one. Like tclaude
proxy, the command only exists when an AWB proxy (agent.awb_proxy.url) is
configured, and both of its daemon endpoints are human-only.
tclaude pickup ls # every process, its issue, and the agent on it
tclaude pickup ls --json # the same, as the daemon's JSON
tclaude pickup watch # live view; r resets the selected process
tclaude pickup reset tcl-backend [--issue tcl-a1]
The listing joins the daemon's dispatch record with the issue's live AWB status
(read with the operator's account) and the live state of the spawned agent, and
condenses them into one state: polling (nothing in flight), held (usage
ceiling), error (the last poll failed), starting, working, idle (the
agent is idle but the issue is open), awaiting (a monitored PR or commit is
recorded and the agent is idle), releasing (the issue closed), stuck (the
agent is retired, gone, or its session is not running while the issue is still
open), and orphaned (a dispatch left behind by a process this daemon no
longer runs).
reset only removes the daemon's dispatch record, so the process polls for the
next ready issue on its next tick. It deliberately leaves the AWB issue and the
agent alone: release or close the issue, and retire the agent, yourself if they
should not continue. An issue that is still ready and unassigned may be picked
up again. A reset waits (briefly) for a poll of the same
process that is already running, so it never cuts off a claim or spawn half
way; if the poll does not finish in time the reset is refused and can simply be
retried. --issue makes the reset conditional on the process still holding
that issue; watch always resets that way, so a refresh cannot redirect a
confirmed reset onto a newly picked-up issue.
Teaching agents to use the proxies¶
installs the agent skill for each configured credential proxy (proxy-git,
which covers git, GitHub and GitLab, proxy-linear, proxy-awb and/or proxy-http) into Claude Code, shared ~/.agents/skills, and Codex home skill
directories. The shared directory is read by Codex, Gemini, Copilot,
OpenCode and pi, so agents discover the semantic commands instead of fighting
their missing credentials. "Configured" uses the host-side rules under
The command only appears when configured.
Setup answers from the config file alone: it deliberately does not consult
per-agent scoped grants or agentd's environment. In particular, a Git proxy
authorized only by a grant's remote scope does not select proxy-git, and a
LINEAR_API_KEY present only in agentd's environment does not select
proxy-linear. Re-running setup refreshes selected skills but deliberately
does not remove previously installed, now-unselected skills. The flag is
deliberately excluded from --install-agent-skills and --install-all: an
operator who has not configured the proxies should not advertise them to
agents.
See also¶
- Sandboxing — the hardening posture these proxies make survivable.
- Permissions and audit — scoped grants, denies,
and
--ask-human. - Network filtering — reaching hosts directly when a proxy is the wrong shape.
Named HTTP(S) proxies¶
Use a generic proxy for services without a semantic integration. Configure instances in the operator's private config; the daemon reads the credential, so the agent does not need access to its file:
{
"agent": {
"http_proxies": {
"inventory": {
"url": "https://inventory.example/api/v1",
"header": "Authorization",
"header_value": "Bearer ",
"header_value_file": "~/service-token.txt"
}
}
}
}
The file can contain just the token, such as secret-token. When both fields
are set, the header is header_value followed by the file contents, with no
implicit separator. The example sends Authorization: Bearer secret-token.
Leading and trailing file whitespace is trimmed; whitespace in header_value
is preserved, including the space after Bearer. Either field can also be used
alone: a file-only configuration should contain the complete header value.
An empty file contributes an empty string; the combined header value must still
be nonempty and valid.
HTTP and HTTPS base URLs are supported, without URL credentials, queries or
fragments. Prefer HTTPS for remote services. Separate instances can use
separate services, API prefixes and credentials. Run
tclaude setup --install-proxy-skills to install the optional proxy-http
skill when this family is configured.
Grant access to one instance by its exact, case-sensitive name:
tclaude agent permissions grant worker proxy.http --scope http_proxy=inventory
tclaude proxy http inventory 'items?limit=10'
tclaude proxy http inventory items -X POST -H 'Content-Type: application/json' --body-file item.json
tclaude proxy http inventory items --json
An unscoped proxy.http grant permits all configured instances. There are no
method or endpoint permissions: this grants full access within the service's
base URL, including writes. It is neither default-granted nor implied by group
ownership. --ask-human 60s requests one-shot approval through the ordinary
permission gate.
Paths are appended to the configured base path; a leading slash has the same meaning as a relative path. Absolute URLs, traversal segments, encoded separators and ambiguous double-encoded paths are refused. The daemon adds the configured header after caller headers, so callers cannot replace it. Host and transport headers are reserved. CONNECT and TRACE are refused. Redirects are returned without following them, and ambient HTTP proxy settings are ignored.
By default the CLI prints the raw response body. --json prints status,
headers and a base64 body, preserving binary data. HTTP 4xx/5xx responses
retain their body and produce a nonzero CLI exit status. --body-file - reads
stdin. Request and response bodies are limited to 4 MiB; credential files are
limited to 16 KiB. Calls have a 60-second daemon deadline and are never
retried automatically. A timeout or unreadable/oversized response can occur
after an upstream write succeeded; check the service before retrying.
The daemon endpoint is POST /v1/http/request, with name, method, path,
optional headers (a string map), and optional body (base64). Its successful
transport response wraps the upstream status, headers and base64 body; an
upstream error status still returns this wrapper. Calls are audited as proxy
operations with the caller's instance-name permission scope.
The dashboard permission editor can grant proxy.http. To limit access, choose configured instance names in its http_proxy scope picker. The permission appears when agent.http_proxies contains at least one instance.
Ordinary HTTP clients¶
Agents launched or resumed by tclaude receive one environment variable for
each instance their effective proxy.http grant permits:
curl --noproxy 127.0.0.1 "${TCLAUDE_HTTP_PROXY_inventory}items?limit=10"
curl --noproxy 127.0.0.1 -X POST -H 'Content-Type: application/json' \
--data-binary @item.json "${TCLAUDE_HTTP_PROXY_inventory}items"
The variable name is TCLAUDE_HTTP_PROXY_ followed by the exact configured
instance name by default. Set environment_variable on an agent.http_proxies entry to override it, for example "environment_variable": "INVENTORY_API_URL". Names must be unique among the proxies granted to an agent and compatible with environment variables (no = or NUL). Custom names replace the default variable. Each value is a base URL with a trailing slash. Use shell-safe
instance names such as inventory or my_service when accessing variables
from a shell. Other environment-compatible names can be read with printenv
or a language's environment map.
These URLs accept ordinary HTTP methods, headers and raw bodies, and return the upstream status, headers and raw body. The launch creates a loopback bridge inside the agent's network namespace; the bridge carries requests to agentd through its authenticated Unix socket. This keeps the URLs usable with isolated networking. The daemon performs the upstream request and adds the configured credential header. The CLI command remains available independently.
URLs include an unguessable local capability for one instance. Treat them as private to the agent. They are not service credentials and are never sent to the upstream service. The daemon also verifies the bridge's live launch pane and generation and rechecks the agent's instance-scoped permission on every request. Revoked permissions immediately stop further upstream requests. The gateway applies the same path, redirect and body limits as the CLI and strips hop-by-hop headers. It does not follow upstream redirects.
Permission and configuration changes take effect in the injected environment on the next launch or resume; existing gateways still enforce current grants. A daemon restart requires the agent's Unix socket to be reachable again, but does not invalidate the bridge's local URL. Gateway request URLs and bodies are excluded from audit and request logs; audit rows record the instance and permission scope. Proxy URL variables are stripped when building another agent's launch so capabilities cannot be inherited by accident.
The raw daemon route is /v1/http/proxy/NAME/PATH, over the existing Unix
socket. GET /v1/http/environment returns only the allowed instance names to
a verified agent or launch bootstrap; it never returns service credentials or
upstream URLs.
Gateway clients must be able to reach loopback in the agent launch namespace. Use --noproxy 127.0.0.1 with curl when ambient proxy settings would redirect local requests. A harness tool running in a separate network namespace may need the Unix-socket tclaude proxy http command instead. Redirect locations and cookie attributes are returned unchanged; the gateway does not rewrite them or follow redirects. If gateway discovery is temporarily unavailable at launch, the agent starts with a warning and without gateway URLs.