Local development and coding agents

A developer’s workstation is a delivery target like any other, with one difference: most commands are now launched by something other than the developer. Coding agents, test runners, and watch-mode restarts run without a terminal. Pick the delivery path with that in mind.

Choose a delivery pathCopy Anchor Link

Export a file is the simplest path and the one every tool understands. Refresh it when values change; it is a projection of the environment, never a second source. Keep it out of version control.

Run with a developer credential delegates your current read and reveal access to one unprotected environment for a fixed working session. Log in and select the trusted instance, organization and project, then mint interactively:

hikyo dev session --env <development-env-id> --ttl 8h
hikyo run --env <development-env-id> -- pnpm dev
hikyo dev session list
hikyo dev session revoke --id <credential-id>
# End all your delegations on the selected instance:
hikyo dev session revoke --all

The selected organization, project and environment must use immutable org_, prj_ and env_ UUID IDs. Log in with the account assurance required by your instance; hikyo account factor step-up raises a password-only session when required. Fresh delegation reauthentication is a separate ceremony.

Mint requires a controlling terminal, explicit consent to every current and future published key in this environment, and fresh scope-bound TOTP or passkey reauthentication. A generic live reveal window is insufficient. The default and hard maximum are eight hours; the instance can impose a shorter ceiling. The CLI resolves that ceiling before consent and binds the confirmed lifetime to mint. You can hold at most four live credentials per instance. There is no renewal.

The CLI stores the bearer in private 0600 state outside the repository, under HIKYO_STATE_DIR or the normal user state directory. Mint prints metadata only. run discovers it only for the exact trusted origin and immutable environment. An explicit service-account credential takes precedence. Developer credentials are not accepted through HIKYO_TOKEN or --token-file.

Ordinary logout or login expiry does not interrupt the fixed delegation. Account security invalidation, explicit revocation, loss of environment access or making the environment protected prevents the next fetch. Ordinary logout reports this and names the revoke command. Already delivered child-process values cannot be erased. Every fetch checks your current read and reveal authorization and records both the developer actor and your human audit authority.

Developer delivery is online-only: no snapshot, cursor, offline audit queue or fallback is read or written. An unreachable server refuses the launch, even if an older service-account snapshot exists. Loader-control acknowledgements, collision checks and execution limits still apply.

Run with a service account remains available for project-owned workloads. Create a service account, grant read on the selected environment, and mint a short finite credential using machine identities. Secret delivery additionally requires the project’s machine-reveal opt-in and a reveal grant. Pass the private token file through --token-file; this path can use the existing Compose offline snapshot policy.

Run with your human session is the locked exception for interactive use. It needs a controlling terminal, an enumerated y/N confirmation on every launch, and a live disclosure window. A coding agent or a scripted test run cannot satisfy it, by design: a process that is not you must not act with your full authority. Use the separate bounded developer credential above for unattended launches.

Administration and incident responseCopy Anchor Link

In Project settings → Developer credentials, a project administrator with manage-identities can inspect every developer credential in that project and revoke one after confirmation. The list shows the credential and developer principal IDs, human delegator, environment, creation and expiry times, and revocation time. It never returns the bearer. Revocation refuses the next fetch; it cannot remove values already delivered to a running process.

In Instance settings → Developer credentials, an operator with instance-config and second-factor assurance can read and change the lifetime ceiling from 1 to 28,800 whole seconds. Lowering the ceiling permanently shortens outstanding credentials to the earlier of their existing expiry and original mint time plus the new ceiling. Some may expire immediately. Raising it later does not extend or revive them. The form explains these consequences before applying the change.

These administration pages do not mint credentials or replace your personal CLI lifecycle. Continue to use hikyo dev session, hikyo dev session list, and hikyo dev session revoke for your own delegations.

What each path protectsCopy Anchor Link

State the threat model honestly. No delivery mechanism keeps plaintext from a process that you, or an agent acting for you, can launch: the child can print its environment, and anyone running as your user can read /proc/<pid>/environ.

• Developer hikyo run writes no plaintext values and prints none. It replaces itself with the child (exec), so it cannot filter what the child prints.
• A service-account offline snapshot changes availability, never disclosure: it is sealed with a local key that the same user can read, and it is served only when the server is unavailable and the project file opts in (Docker Compose delivery).
• The controls that matter are what the development environment is allowed to contain and how long the credential lives. Keep production secrets out of development; give it development-only databases and test-mode API keys.

For coding agents specifically: an agent that can start your dev server holds every value that server holds. Injection without printing keeps secrets out of files, logs, and the agent’s view of command output; it does not create secrecy from the agent.

Compose with an application-side loaderCopy Anchor Link

Hikyo stores, authorizes, audits, and delivers values. It does not validate them against your application’s schema, generate types, or redact your process output. Application-side loaders such as varlock do exactly that and read the process environment, so the two compose without a plugin:

hikyo run -- varlock run -- pnpm dev

Hikyo fetches and injects the development values; varlock validates them against .env.schema, fails fast on a missing or malformed key, and masks values marked @sensitive in piped or redirected output. Redacting console output on a terminal needs varlock’s runtime integration in the application.

Precedence across the two layers:

• Values already in the process environment take precedence over .env files in varlock, so a stale local .env is shadowed by the delivered values for every key Hikyo delivers, without a warning. Delete it once you switch.
• --allow-override concerns only keys your shell exported before hikyo run started. An inherited key with a different value is refused unless you name it; .env files are not inherited environment and never trigger it.
• varlock masking covers only keys marked @sensitive and cannot reliably mask very short values. Mark every key Hikyo classifies as secret as @sensitive so the two classifications agree.

hikyo run refuses loader-control keys such as NODE_OPTIONS, PATH, LD_*, GIT_*, and NODE_EXTRA_CA_CERTS unless a hikyo-compose.yaml names them in run.acknowledge_loader_control. Keep them out of the development environment unless the process genuinely needs them.

Continuous integrationCopy Anchor Link

CI does not need a stored credential. Bind the CI job to a service account with OIDC federation. The job then requests an ID token for the binding’s audience from its platform and presents it through --token-file or HIKYO_TOKEN, with the same hikyo run -- <command> or one export per job.

How Hikyo relates to similar toolsCopy Anchor Link

• varlock is complementary: it owns the application contract (schema, types, validation, redaction, client-bundle leak guards) and has no store, audit, or delivery. Use both, as above.
• dotenvx makes an encrypted .env file in Git the store, with one private key per environment file. That trades Hikyo’s per-key presence rules, reveal audit, and revocation for having no server. Choose one model per environment, not both.
• 1Password, Infisical, and Doppler run wrappers deliver the same way hikyo run does. Unlike Infisical and Doppler, Hikyo refuses a changed inherited value instead of overriding it with a warning, and serves its snapshot only while the server is unavailable. Unlike op run, it does not mask the child’s output; pair it with a loader that does.

Next: deliver to Docker Compose.