Coding agents are happiest when they have a real CLI to call and a narrow blast radius to work in. The Forgecroft CLI is designed for exactly this: every command has a stable flag surface, --json output for parsing, and the credentials are scoped per-key so you can hand out exactly the permissions you want.
The two-key model
When you onboard in agent mode (either from the console wizard or forgecroft onboard --mode agent), Forgecroft issues two distinct API keys. They exist because the daemon and the coding agent are different principals with different risk profiles, and collapsing them into one key would force you to pick between “too powerful” and “too limited”.
| Runner key | Onboarding key | |
|---|---|---|
| Who uses it | forgecroft-agent daemon | CLI, CI, coding agents |
| Scope | Org-scoped | Workspace-scoped |
| Verbs | Runner internals | read, trigger |
| Lifetime | Permanent | 12 hours |
| Where it lives | Infra you control | Developer machines |
Give the runner key to your infrastructure. Give the onboarding key to the CLI and, from there, to your coding agent.
Hand a key to your coding agent
Export the key as an environment variable in the shell your coding agent runs commands in:
export FORGECROFT_API_URL=https://api.forgecroft.com
export FORGECROFT_API_KEY=fc_live_...
The key is workspace-scoped with only read + trigger, so the worst thing a runaway agent can do is trigger plans against a single workspace you already intended to manage. It cannot approve runs, manage keys, or reach other workspaces.
Tell the agent what it can do
Drop a short note into your project’s CLAUDE.md, AGENTS.md, or equivalent so the agent knows the CLI exists and how to use it:
## Forgecroft
You can manage infrastructure runs with the Forgecroft CLI. The key in
$FORGECROFT_API_KEY is scoped to the `production` workspace with read +
trigger verbs. You cannot approve runs or create new API keys.
- Trigger a plan: forgecroft runs plan $FORGECROFT_WORKSPACE_ID
- List recent runs: forgecroft runs list --workspace $FORGECROFT_WORKSPACE_ID
- Read logs: forgecroft runs logs <run-id>
Prefer --json output when parsing results.
Coding agents we have tested against: Claude Code, Codex, Cursor. Any agent that can execute shell commands and read stdout works fine — the CLI has no agent-specific surface.
When the 12 hours are up
The onboarding key expires 12 hours after it was minted. When you are ready to commit to the integration, open Settings → API Keys in the console and either:
- Click Make this permanent on the onboarding key (it loses its
expires_atbut keeps its workspace scope), or - Create a brand new key with the exact scope you want for longer-term use.
The “make permanent” shortcut is also available directly on the onboarding success screen in the console wizard.
Defense in depth
The short TTL + workspace scoping + verb scoping combination is deliberate:
- TTL limits how long a leaked key is useful.
- Workspace scope limits where a leaked key can do damage.
- Verb scope limits what it can do there.
None of these are sufficient alone — together they make it safe to paste a key into a developer machine without spending an afternoon thinking about blast radius.