Terminal
Terminal/Skill
Runs a local Ory login and permissions stack in Docker, so you can build and test auth flows without an Ory project.
By Ory
Works with
npx skills add ory/claude-plugins --skill ory-local-devYou are helping the user develop an authentication application against a
local Ory stack running in Docker — not against Ory Network. The
@ory/claude-code plugin ships two commands that
manage the lifecycle:
/ory-agent-plugin:local-up — start Kratos, Keto, Hydra, and an Nginx gateway,
then seed a test identity, session, and permission tuples./ory-agent-plugin:local-down — stop all services while preserving data volumes.Both delegate to npx -y -p @ory/claude-code ory-claude local <subcommand>, so the same
workflow runs from the shell when the command shortcuts are not available.
Pick the local stack over Ory Network when any of these are true:
local reset).If the user already has an Ory Network project and just wants their
production app wired up, prefer the /project:ory-auth-setup skill and
point the SDK at the Network URL instead.
/ory-agent-plugin:local-up gives youAfter /ory-agent-plugin:local-up completes:
| Service | URL | Purpose |
|---|---|---|
| Gateway | http://localhost:4000 | Unified API (mirrors Ory Network) |
| Agent Security | https://agents.console.ory:8080 | Canonical permission/delegation broker |
| Kratos public | http://localhost:4433 | Self-service flows (login, etc.) |
| Kratos admin | http://localhost:4434 | Identity & session admin |
| Keto read | http://localhost:4466 | Permission checks |
| Keto write | http://localhost:4467 | Relation tuple writes |
| Hydra public | http://localhost:4444 | OAuth2 / OIDC |
| Hydra admin | http://localhost:4445 | OAuth2 client management |
The seed step also produces:
agent@ory-local.dev/ory-agent-plugin:local-up)AgentTool namespace for common tool namesory-agent-plugins-local, client_credentials grant)The local stack is Docker Compose under the hood. Before invoking
/ory-agent-plugin:local-up, confirm Docker is available:
docker info
If Docker is not running, ask the user to start Docker Desktop (or their docker engine) and retry. Do not try to install Docker for them.
Tell the user to run /ory-agent-plugin:local-up, or the equivalent shell command:
npx -y -p @ory/claude-code ory-claude local up
Wait for the command to print "All services are running!" and the seed output. Configure these connection values:
ORY_PROJECT_URL (always http://localhost:4000)ORY_AGENT_SECURITY_URL (https://agents.console.ory:8080; run the Agent Security service separately)ORY_OAUTH2_CLIENT_ID (the seeded PKCE login client)If the user wants to skip seeding (to bring their own data), use
npx -y -p @ory/claude-code ory-claude local up --no-seed instead.
The local gateway is a drop-in replacement for the Ory Network SDK URL. Configure the auth app exactly as you would for Ory Network, but point at the gateway:
Environment variables (.env.local or shell):
NEXT_PUBLIC_ORY_SDK_URL=http://localhost:4000
ORY_SDK_URL=http://localhost:4000
For Next.js, that is the only change needed in
/project:ory-auth-setup's SDK configuration. For React SPAs, use the
same value as basePath in the Ory Configuration.
Persist it across plugin sessions (so all Ory agent plugins on this machine target the local stack):
npx -y -p @ory/claude-code ory-claude local configure
This writes the URL to the shared plugin config so future agent runs do not need the env var.
Use the existing skills for the UI layer — they apply unchanged when the SDK points at the local gateway:
/project:ory-auth-setup — full Ory Elements bootstrap (this is the
default UI path, including against the local stack)./project:ory-login-flow — login, registration, recovery,
verification, settings pages.Skip the Ory Tunnel step when developing against the local stack. The tunnel only exists to bridge cookies between localhost and Ory Network. The local gateway already runs on localhost, so cookies work directly.
Two ways to exercise the flows:
<Registration> page. This validates the
self-service flow end-to-end.agent@ory-local.dev
with password ory-agent-local-dev-password! to test session-bearing
pages without going through registration.For automated tests against the running stack, log in through Kratos to get a session token and call the session API with it:
KRATOS_SESSION_TOKEN=$(...) # from a Kratos login flow
curl -H "X-Session-Token: $KRATOS_SESSION_TOKEN" \
http://localhost:4000/sessions/whoami
That token is a Kratos session token — it authenticates the Kratos
session API only. It is not what the plugin uses: the plugin's env
credential (ORY_USER_OAUTH2_TOKEN) must be an OAuth2 access token,
because it authenticates delegation and can bootstrap the agent's OAuth2 client.
Common day-to-day commands:
| Need | Command |
|---|---|
Re-seed (after local reset) | npx -y -p @ory/claude-code ory-claude local seed |
| Tail Kratos logs | npx -y -p @ory/claude-code ory-claude local logs kratos -f |
| Check what's running | npx -y -p @ory/claude-code ory-claude local status |
| Print env vars to copy/paste | npx -y -p @ory/claude-code ory-claude local env |
If the user reports flaky behavior, run local status first to confirm
each service is healthy. If a container is unhealthy, local logs <service> is the next step — do not jump to local reset until you
have looked at logs.
When the user is done for the session, use /ory-agent-plugin:local-down (equivalent:
npx -y -p @ory/claude-code ory-claude local down). Containers stop but volumes
remain, so the next /ory-agent-plugin:local-up reuses the same identities,
sessions, and tuples.
For a full wipe (e.g., after schema changes or to clear test data):
npx -y -p @ory/claude-code ory-claude local reset
reset removes data volumes and the generated .ory-dev/ory/ directory.
The next local up regenerates configs from scratch — useful when the
plugin updates the bundled service configs.
/ory-agent-plugin:local-up.npx -y -p @ory/claude-code ory-claude local logs gateway and npx -y -p @ory/claude-code ory-claude local logs kratos to see which service
failed. Port conflicts on 4000, 4433, 4444, or 4466 are the
usual culprit.whoami returns 401 — the cookie domain is
wrong. Make sure the app runs on http://localhost (not 127.0.0.1)
and the SDK URL is exactly http://localhost:4000.http://localhost:3000, no CORS
config change is needed. For non-localhost dev URLs, switch back to
the Ory Tunnel + a Network project.AgentTool namespace. If your app uses a different namespace, set
ORY_PERMISSION_NAMESPACE before local seed, or write the tuples
manually via the Keto write API on :4467./project:ory-auth-setup and
/project:ory-login-flow./project:ory-social-login. Note that
most social IdPs require public callback URLs, so you will typically
swap to Ory Network when you reach that step.http://localhost:4000.