Credentials

A variable listed under credentials never reaches the container: Kraft's egress proxy adds its value to requests instead. This page covers how to declare one, how it works and its limits.

repos:
  - path: /home/you/code/my-service
    sandbox:
      kind: docker
      image: ghcr.io/acme/agent@sha256:...
      network:
        runtime: {allow: [registry.example.com]}
      credentials:
        - env: ANTHROPIC_API_KEY          # its harness says how
        - env: REGISTRY_TOKEN             # the repository's own, in full
          service: registry
          inject: [{domain: registry.example.com, header: authorization, format: "Bearer %s"}]

The container gets a sentinel in the variable's place, and Kraft's egress proxy puts the server's own value into the named header on requests to the named host.

This holds for every sandboxed launch of the item: agent sessions, subprocess tasks, test scopes and setup commands, whose code the worker may have written. A variable not listed passes through as Sandboxed workers describes. Nothing is managed unless the repository lists it.

Credential fields

Each entry under credentials has these keys. env alone takes the rest from the harness file of the session's CLI (see Credentials a harness declares); a repository's own credential gives service and inject itself.

phase

[install] is the setup command. [runtime] is agent sessions, subprocess tasks and test scopes. A launch in another phase gets neither the sentinel nor the value. Unset, the credential is in both.

source

source names the server's own environment variable its value is read from, instead of env in the worker's environment. The worker's environment is never read for it, not even as a fallback, and the source variable is kept out of the container as env is. Set but empty counts as no value.

Rules for the list

• credentials needs network. It is part of the sandbox, so a chain, node or task cannot change it.
• A repository's own credential's domain must be named in the allow list of each phase its phase lists (either phase, when unset), and not denied there. A wildcard or a harness's hosts do not count.
• A variable can be listed once per phase, and one header on one host set by one credential per phase. One name can therefore serve two entries whose phase lists do not overlap.
• Anything else fails when repos.yaml loads.

Credentials a harness declares

A harness file declares the variable, header and host for its CLI, so env: NAME alone is enough. Harness definition files lists what the shipped claude, codex and gemini files declare.

• A CLI that pins its host's certificate, or needs HTTP/2, cannot be managed this way, and its variable should stay unlisted.
• A CLI whose harness does not declare the name gets the sentinel and nothing injected.

How credentials work

When a session manages a credential, its container's CA bundle (mounted at /etc/kraft/ca-bundle.pem, as for an extra CA) also holds Kraft's own CA.

For a host with a managed credential that the session's phase allows by name, Kraft does not tunnel the CONNECT. Instead the proxy:

1. Answers the worker's TLS itself, with a certificate Kraft's CA issued for exactly that host. It refuses a handshake that names another.
2. Makes its own TLS connection to the real host, verified against the server's own roots plus the extra CA, never Kraft's.
3. Passes each request on, one at a time, keep-alive and pipelined included.

A request is answered 403 and recorded as a refused host, and never reaches the host, when:

• its Host is not the host it connected to
• any instance of the credential's header is not exactly the sentinel in its format
• it carries no managed credential's sentinel at all

That way the worker cannot use the route with a key of its own.

Otherwise every instance of the header is dropped and one set to the real value. A server that has no value refuses those requests rather than forward the sentinel. Every other host stays a blind tunnel, including one allowed only through a wildcard, and a plain http:// request to a managed host is refused.

Where the value is kept

The value is read the way the rest of the worker's environment is: the server's own, a name in env_passthrough, or env. A credential with source reads the server's own variable of that name alone.

Kraft keeps it only in the server's memory and puts it only in the header on its way out. It is not in the container's environment, argv, mounts, docker inspect (which shows the sentinel), the docker client's environment, an event, a log line or the session's row.

kraft admin doctor lists, for each sandboxed repository with credentials:

• which names are managed and on which hosts
• which names a harness declares that still pass through

A managed name with no value (under its source, for one that has one) fails the row, and a credential with phase says which. A name listed alone that no harness declares, such as OPENAI_API_KEY for Codex (whose name is CODEX_API_KEY), warns, naming what each harness does declare: it holds only its sentinel and nothing injects it.

Credential limits

• HTTP/1.1 only. The terminated connection offers only http/1.1, in both directions. A CLI that needs HTTP/2 does not get it, and a WebSocket or any other upgrade does not work to a managed host: a 101 ends the connection. Codex opens a WebSocket to its host first. Against a stand-in host it falls back to HTTPS; whether it does when the real host's 101 ends the connection is untested.
• Responses pass back as they are. Only the request is rewritten. A host that echoed the real key in a response header or body would hand it to the worker; Kraft does not strip it.
• Listing a credential does not clean the item's HOME.
  • A sandboxed item keeps one HOME, $KRAFT_HOME/run/sandbox-home/<work item id>, across its sessions.
  • A session that ran before the variable was listed had the real value, and its CLI may have saved it there, in a login or config file.
  • To start clean, pause the item and delete that directory. Kraft makes an empty one at the next session, and that session starts without the CLI's saved state, so it cannot resume the earlier one. kraft view show prints the work item id.
• After a server restart, a running session's credentials are restored with the rules it launched with, and their values are read again through the repository entry it launched with. If that repository has been disconnected, its repos.yaml no longer loads, or the value is gone, its requests carrying the sentinel are refused until the item is retried.

Related

• Network policy: the network a credential needs.
• sandbox.yaml: credentials, which binds a Kit's credentials to server variables.
• Give a worker its login: giving a harness its login outside a sandbox.