Concepts
Local CLI execute
Official Kody doc
When Node ≥22 and @kodycodes/cli are available, prefer
npx @kodycodes/cli execute --local for one-off modules, smoke tests, and
composition. Local execute is orthogonal to Open API: the CLI runs your
module in a local workerd and forwards each kody:runtime call through the
CapabilityProxy. Do not use hosted MCP execute for agent work when a local
or Open API path exists.
--local runs a pinned workerd on Linux, macOS, and Windows (x64 or arm64;
Windows on Arm uses the x64 workerd build). No Docker required.
Local workerd uses a real clock: Date.now() and performance.now() advance
during CPU-only code, while hosted runs only advance them across I/O (see
Server-Timing phases (raw)), so local
timings of synchronous work do not match hosted ones.
Watch: Where Kody code runs: the cloud, your laptop, or your own machine.
Auth: --token / KODY_API_TOKEN (kody_at_… with org:execute; add
package:execute when the module imports kody:@…), then the one saved CLI
credential from kody login or kody auth bootstrap (a kody_at_… device
token, not host MCP OAuth). kody whoami reports the same pick.
Setup
Agents already on MCP (do this yourself; never ask a human for a token):
call cliCredentialBootstrap with no params (single-task agents may pass
lifetime: "short", which has no refresh: anything that waits, like a ship-pr
loop on CI, needs the default). Prefer MCP api with
operationId: "cliCredentialBootstrap" (or the capability via search when you
need the schema). It returns a one-shot kody_bc_… code and a cli_command
that includes lifetime flags for older CLIs (not a kody_at_…). Bootstrap
tokens are person-owned (org_binding: user); pass ?org=<slug> on API calls
to act in a team org (default: personal). Run the returned cli_command (no
second OAuth, no tokenCreate):
{
"operationId": "cliCredentialBootstrap",
"params": {}
}# Or run the cli_command returned by cliCredentialBootstrap:
npx @kodycodes/cli auth bootstrap --code 'kody_bc_…'Omit lifetime for the same lifetime as kody login (long = 14 days idle / 3
months max, clamped to a parent API token). short is 1 hour idle / 24 hours
max. Or pass both --idle-ttl-seconds and --max-lifetime-seconds.
tokenCreate still requires a lifetime.
Omit scopes for the same scopes as kody login: every org permission, capped
by your org role on each request and by a parent token or a session that narrows
scopes. Pass scopes only for a deliberately narrower token; the list replaces
the default, so include every scope you need. Prefer MCP search for discovery
(search:read is not required).
# Agents on MCP, with the api tool (execute is refused): cliCredentialBootstrap({})
npx @kodycodes/cli auth bootstrap --code 'kody_bc_…'
# Optional: save a deliberately narrower credential (replaces the default):
npx @kodycodes/cli auth bootstrap --lifetime short \
--scopes org:execute,org:read,package:execute,package:read,package:writeRedeeming a code saves the same credential kody login saves: every scope your
org role grants (never more than the authorizing MCP session holds), 14d idle /
3mo max, in the same slot. --scopes is only for a narrower credential; it
mints with --token when given, else KODY_API_TOKEN, else the saved
credential, and a child never exceeds its parent. --code with --scopes is an
error because a code's scopes are fixed when it is minted.
Interactive humans: kody login once per machine (beside the agent
cliCredentialBootstrap path above), then run --local without
KODY_API_TOKEN.
npx @kodycodes/cli login # onceOn a remote VM, NAS, or SSH session, use npx @kodycodes/cli login --device and
approve the printed code from any browser. See
Remote or headless machines (raw).
CI / headless only: scoped KODY_API_TOKEN (kody_at_… with org:execute,
plus package:execute for saved-package imports), usually from MCP api
tokenCreate with a required lifetime. Put the value in the environment; never
paste it into chat (agents on MCP must use cliCredentialBootstrap instead).
Prefer the env var over --token. When set, KODY_API_TOKEN wins over
kody login / bootstrap store. Minting details: Open API
(guide:open_api).
{
"operationId": "tokenCreate",
"params": {
"name": "kody-cli-local",
"scopes": [
"org:execute",
"org:read",
"package:execute",
"package:read",
"integration:read",
"integration:use",
"secret:use"
],
"lifetime": "short"
}
}export KODY_API_TOKEN='kody_at_…'Usage
npx @kodycodes/cli execute --local --code 'import { kody } from "kody:runtime"; export default async function main() { return await kody.metaGetCurrentUser({}) }'--code accepts TypeScript, like execute on Kody cloud; so do runs routed to
an execution context.
Use --file path.ts the same way when the module lives on disk. Keep --local;
static kody:@owner/name imports still run locally (package-graph download +
CapabilityProxy hops). The CLI posts the kody:@ imports that still need
published modules to POST /v1/local-execute/package-graph (with a tiny
synthetic entry), never the whole module. Inline code on that route may be up
to just under the Open API JSON body limit (~5 MiB); larger callers pass
imports alone so origin synthesizes a tiny entry. If inline code still
exceeds that ceiling, the API (and CLI) name the actual UTF-8 byte length and
the maximum — not a bare Invalid parameters. Package-graph always returns the
gateway-fetch shim, so ad-hoc scripts with no kody:@ imports still expand
{{secret:…}} placeholders on origin (or fail closed naming the secret) instead
of sending them raw. import { credential } from 'kody:runtime' for ad hoc and
unpublished package source needs a CLI whose host kody:runtime exports
credential / credentials per the
CLI local credential runtime
contract (CapabilityProxy opens a handle; gateway placement only — same as
hosted). Older CLIs fail at import time; upgrade @kodycodes/cli.
A fetch that carries a placeholder runs on origin with the same 5-minute
overall deadline as cloud fetches. The deadline starts when origin sends the
request upstream, after it checks your quota and fills placeholders, and runs
until the response body ends. The response is also aborted after 60s with no
bytes. --local has no run cap, so a long streamed response, such as an AI
completion, can finish.
Small buffered placeholder-bearing bodies use the JSON CapabilityProxy hop
(kody.gatewayFetch): origin buffers the whole response before returning it, so
your code receives nothing until the body ends, and a body over 4 MiB fails.
Streamed bodies, multipart bodies, and bodies that would exceed 4 MiB use the
streaming hop (POST /v1/capability-proxy/gateway-fetch via
kody.gatewayFetchStream): there is no 4 MiB hop cap. That path still respects
the Cloudflare Worker upload limit (~100 MiB on Free/Pro). A Content-Length
over that limit returns JSON 413 payload_too_large. See the
CLI streaming gateway-fetch contract.
The CLI CapabilityProxy client waits up to 7 minutes for origin's reply, so the
gateway's 5-minute deadline ends a slow fetch, with its own error. Set
KODY_CAPABILITY_PROXY_TIMEOUT_MS (milliseconds) to change that wait for slow
capabilities. When it runs out, the module fails with a
Kody API sent nothing for …ms error that says the call may still be running on
Kody. @kodycodes/cli below 1.13.1 hits Node's default 300-second wait
(UND_ERR_HEADERS_TIMEOUT) instead. With NODE_USE_ENV_PROXY=1 or
--use-env-proxy, these requests still go through HTTP_PROXY / HTTPS_PROXY.
A fetch without placeholders, and a multipart upload that does not need fill,
goes straight from local workerd and is not subject to this deadline.
Running from a package checkout
Run --file from inside a package directory and the CLI resolves that package's
own kody:@… exports (and .kody/deps.json mappings) from the working tree.
Their remaining kody:@ dependencies come from published package-graph. When a
successful package-graph response omits required modules, the module never
ran: that error (incomplete_package_graph in --json output) is a package
resolution problem, not an auth problem. HTTP 401 or 403 from package-graph is
still auth or permission — use the Failure section below. Two workarounds for
incomplete_package_graph:
- Inside the checkout, import your own package's files with relative imports
(
./src/helper.ts) instead ofkody:@scope/pkg/helper. - To test the published exports, run the entry from a directory outside the
checkout so every
kody:@import resolves from package-graph.
Failure
- Node is below 22, the CLI is missing, or the host cannot run workerd. Use
Open API / MCP
api, or fix the environment. Hosted MCPexecutestays banned for that failure case. - Not authenticated (missing or invalid credentials). Agents on MCP: call
cliCredentialBootstrapand run the returnedcli_command; never ask a human to paste a token. Humans:kody login. CI/headless:tokenCreate+KODY_API_TOKEN. - The bootstrap code expired or was already used. Call
cliCredentialBootstrapagain and run the newcli_command. insufficient_scopeon a token means it lacks a scope. The error names the scope and prints both mint commands with the full list (the token's scopes plus the missing one); run one and retry.--tokenandKODY_API_TOKENstill win over the saved credential, so replace or unset them before retrying. The error also says which credential was sent (Credential used: …). Open API errors carry the same list asdetails.mint_scopes. When your org role lacks the permission (denial: missing_permission), a new token cannot help; an org Owner has to grant it.profile_grantmeans the profile the token acts as (or a parent) was not granted that package or credential. A new token alone cannot fix it; the person the profile acts for grants it (accessGrantwithsubject_type: "profile"). If the message says the token also lacks the scope, mint one with it after the grant.profile_inactivemeans the profile or a parent was revoked or expired; use a token for an active profile.- Package-scoped
secretSet/secretSetMany/secretDeleteare not available under--local. Local CapabilityProxy does not attach package secret authority (a client-supplied package id is not trusted as a hosted run). Use hosted package execute, or set the secret from the account UI (/connect/secret-set) or Open APIsecretSetwith a user scope / outside local execute. See Secrets. - Package-graph prep that exceeds the throwaway isolate's memory or CPU returns
400 package_graph_resource_limit(the error names the packages). A served graph missing a reachable static relative import is500 internal_error. See Open API architecture. - The module imports
kody:@…. Keep--local. - Auth priority for
--local(and every other command):--token/KODY_API_TOKEN, then the one saved CLI credential fromkody loginorkody auth bootstrap.kody whoamireports the same credential. A token an older CLI left in the old API-token slot is moved into the saved credential only when nothing else is saved and no--org/KODY_ORGis given;kody logintries to delete it.