How to use the smolvm Credential Binding agent skill

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder of instructions and scripts that an AI agent can load when a task matches it. This skill, named credentials, covers one job: giving a workload inside a smolvm machine an API key or token it can use but never read.

It does this by binding the credential to named HTTPS hosts. The guest machine holds only a placeholder. When a request leaves the machine for a bound host, the host substitutes the real value into the request header. The skill then proves on the host that the value never entered the machine.

• Use it when an agent or untrusted code inside a machine must call an API with your key.
• Use it to decide between a credential binding and --secret-env.
• Use it when a request from a credentialed machine returns 403 or 502 from smolvm itself.
• Use it when you need evidence that a key stayed out of a machine.
• Do not use it for a value the program must read and parse, such as a database URL. That is --secret-env. Do not use it for git or ssh keys either; those are handled by SSH agent forwarding.

How do you install the credentials skill?

Download the ZIP of the skill from this page and unzip it. For a personal setup, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

The package contains SKILL.md, README.md, two reference files (references/platforms.md and references/traps.md) and four scripts in scripts/: preflight.sh, create-credentialed.sh, verify-containment.sh and cleanup.sh.

• Requirements: smolvm, a macOS arm64 or Linux aarch64 host, a Bash shell, and network access to the API host you bind.
• The verification step installs openssl and curl with apk in an Alpine guest image.
• Your API key must be set as a host environment variable.

How do you set up a credential binding, step by step?

Follow the procedure in SKILL.md in order. Each step has a script and a expected output, so you can see whether it passed.

First, run the preflight check. It is read-only and never prints the value or its length. Keep the variable exported in the same shell for every later script, because each script reads the value from its own environment.

Then create the machine bound to one host, and run the containment check before any workload of yours runs in it. Only then make your own request, and clean up when finished.

• Preflight reports result=ready when the machine can carry a credential.
• create-credentialed.sh prints result=up and guest_sees=placeholder when the guest holds only the placeholder.
• verify-containment.sh should print result=contained, with value_in_guest and value_in_record both at 0 matches.

How do you trigger the skill with natural requests?

You do not need to name the skill or its scripts. Describe the situation in plain words and the agent should match it against the skill's description.

Requests that fit well describe a machine, a key and a host together. Be specific about the API host so the binding can be limited to it.

• Set up a smolvm machine so the agent can call api.example.com with my API token, and prove the token never gets into the machine.
• Should I pass this database URL to my smolvm machine with a credential binding or with --secret-env?
• My request from the smolvm machine came back 403. Is that smolvm or the API?
• Give me evidence that my key stayed out of this sandbox.

What do the verification results mean?

The containment check looks for the value in several places and reports each one. value_in_guest searches every process environment and the writable trees inside the guest. value_in_record searches the machine's directory and smolvm's database on the host.

interception confirms that the bound host's certificate is issued by the machine's own CA, named smolvm followed by the machine name and credential CA, while the other host you pass keeps its real issuer. passthrough and query_refused confirm that unbound traffic is relayed normally and that a placeholder in a query string is refused.

• A 403 whose body says placeholders are substituted in request headers only means smolvm refused a placeholder outside a header.
• A 403 that says this credential is not allowed for this host means the placeholder belongs to a binding for another host.
• A 405 means the binding does not allow that HTTP method.
• A 502 with a smolvm credentials body comes from smolvm, not the API.

What should you watch for when you use it?

Read the safety notes before you run anything. The skill runs scripts on your host and makes network requests to the bound API. The containment check runs grep inside the guest, so a workload that can replace grep could read the value. Run the check before any of your workloads start in that machine.

Port 80 is not intercepted. Plaintext HTTP is relayed untouched, so a placeholder sent there reaches the API as the literal string. Use HTTPS to the bound host.

If you need the workload to read the value, use --secret-env instead. The value is then plaintext inside the guest, where any process can read it and send it anywhere the network allows.

• Rotating an environment value takes effect only after the machine restarts.
• Never put the real value on an exec command line, because smolvm writes exec commands into the machine's console log on the host.
• Ephemeral machines retire after their run returns, so cleanup.sh waits up to 20 seconds for them to leave the machine list.