Skip to content
DocsLocal CLI execute

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:write

Redeeming 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   # once

On 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 of kody:@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 MCP execute stays banned for that failure case.
  • Not authenticated (missing or invalid credentials). Agents on MCP: call cliCredentialBootstrap and run the returned cli_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 cliCredentialBootstrap again and run the new cli_command.
  • insufficient_scope on 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. --token and KODY_API_TOKEN still 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 as details.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_grant means 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 (accessGrant with subject_type: "profile"). If the message says the token also lacks the scope, mint one with it after the grant. profile_inactive means the profile or a parent was revoked or expired; use a token for an active profile.
  • Package-scoped secretSet / secretSetMany / secretDelete are 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 API secretSet with 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 is 500 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 from kody login or kody auth bootstrap. kody whoami reports 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_ORG is given; kody login tries to delete it.

Working with an agent? This page is also plain markdown at /docs/local-execute.md, or load it over MCP with search({ entity: 'guide:local_execute' }).