buckle run wraps a coding agent process with Buckle gateway access. Your agent’s HTTPS traffic routes through the gateway, which injects stored credentials automatically. The agent never sees raw API keys or OAuth tokens.
Supported agents
Any command works after
--. The agents listed above also get an auto-installed skill file that teaches them how to use the gateway.
Setup
1
Start Buckle
2
Install the CLI
3
Launch your agent
buckle: gateway connected. Starting claude... and your agent starts with the gateway configured.What buckle run does
When you run buckle run -- claude, the CLI:
- Fetches gateway configuration from the Buckle server
- Writes a CA bundle (your system CAs plus the gateway CA) to
~/.buckle/ca-bundle.pem - Installs the Buckle gateway skill into the agent’s skill directory (for Claude Code,
~/.claude/skills/buckle-gateway/SKILL.md), fetched from the server with a built-in fallback - Injects
HTTPS_PROXY, the CA trust variables (SSL_CERT_FILE,NODE_EXTRA_CA_CERTS, and friends), andBUCKLE_GATEWAY=trueinto the child process - Hands over terminal control to the agent
Choosing the agent identity
Eachbuckle run session acts as one agent from your project, which decides the credentials the gateway injects and the rules that apply. The identity resolves in this order:
--agent <identifier>flagBUCKLE_AGENTenvironment variablebuckle config set agent <identifier>(requires CLI 2.10+)- The project’s default agent
buckle run is unaffected.
How agents connect to services
The skill file teaches supported agents a simple workflow:-
Make the request directly. The agent calls the real API URL (e.g.
https://gmail.googleapis.com/...). No auth headers needed. If credentials are configured, the gateway injects them and the request succeeds. -
If it fails, help the user connect. The gateway returns a structured error with a
connect_url, and the agent presents that link to the user. - Poll and retry. The agent polls the connection status and retries automatically once the user connects the service. No manual “try now” needed.
buckle secrets create.
Flags
Dry run
Use--dry-run to inspect what buckle run would do without side effects:
Compared to the SDK path
buckle run is for coding agents running directly on your machine. If your agents run in Docker containers (e.g. via NanoClaw), use the Node.js SDK instead. Both paths use the same gateway, the same secrets, and the same policy rules.