Authentication and security

Picoo keeps credentials out of operation packages. An operation declares what it needs, while you control the values and the policy that allows access.

Separate the three auth layers

Agent login belongs to Claude, Codex, Hermes, or another client. Picoo does not need the model provider key to run local operations.
Registry access installs private operations. It is not passed to operation code. See the Registry guide.
Operation auth belongs to the service used by an operation, such as a GitHub token for creating an issue.

Separating them lets you rotate or revoke one credential without changing the others.

Log in to the Registry

Ask the Registry operator for a token limited to write:package. Store it with the credential helper already configured for Git:

picoo auth login --owner alice
picoo auth status --owner alice

The normal prompt hides the token. Picoo sends it to Git’s credential protocol over standard input and never places it in a command argument or Picoo config file. Picoo refuses Git’s plaintext credential.helper=store; configure Git Credential Manager, macOS Keychain, libsecret, or another protected helper.

For an agent or secret manager, pipe the secret without putting it in the prompt or command line:

secret-command | picoo auth login --owner alice --token-stdin

Publishing automatically uses that stored credential. CI should instead inject PICOO_FORGEJO_TOKEN as a masked secret. Environment credentials take precedence over stored credentials.

Remove local access when it is no longer needed:

picoo auth logout --owner alice

Forgejo OAuth is intentionally not used for publishing. Forgejo’s current OAuth tokens are not scope-limited, while a Registry token can be restricted to the package API.

Declare operation auth

When creating an operation, declare the provider, secret variable, and network host:

picoo create alice/github/create-issue \
  --runtime python \
  --description "Create one GitHub issue" \
  --input repo:string \
  --input title:string \
  --output issue_url:string \
  --auth github \
  --secret-env GITHUB_TOKEN \
  --network api.github.com

The manifest stores the name GITHUB_TOKEN, never its value.

Set the value outside Picoo

For direct terminal use:

export GITHUB_TOKEN="your-token"

$env:GITHUB_TOKEN = "your-token"

Picoo starts every operation with a clean environment. It passes essential runtime values, declared non-secret variables, and declared secret variables. Unrelated parent secrets are not inherited.

Allow access through MCP

The MCP server has three separate allowlists:

picoo mcp serve \
  --allow-op alice/github/create-issue \
  --allow-network api.github.com \
  --allow-auth github

All three must match the operation manifest. The client must also forward GITHUB_TOKEN to the Picoo process through its environment settings.

Choose safer credentials

Create a separate token for agent operations when the service allows it.
Give it only the scopes required by the operation.
Prefer a short expiry.
Rotate it after accidental exposure.
Revoke it when the operation is no longer used.
Use a test account for early development when practical.

Review before granting access

picoo show alice/github/create-issue

Check the operation ID, version, input, output, network hosts, auth provider, and secret variable names. For packages from a Registry, require a trusted signature when your security policy calls for it.

Use sandboxing when available

picoo run alice/github/create-issue --sandbox --input repo=owner/project --input title="Fix login"

For MCP:

picoo mcp serve --allow-op alice/github/create-issue --require-sandbox

--require-sandbox fails closed. If Picoo cannot provide its operating system sandbox, the operation does not run or appear through that MCP server.

Troubleshoot safely

A credential is missing. Check that the variable name matches the manifest, is set in the parent process, and is forwarded by the MCP client. Do not print the value.

Policy rejects the operation. Compare picoo show OPERATION_ID with the MCP allowlists. Add access only after reviewing why the operation declares it.

Authentication fails at the service. Check the token scope, expiry, and account access. Rotate the token if its history is uncertain.

Recap

Agent, Registry, and operation credentials are separate.
Registry publishing tokens belong in a protected credential helper or CI secret.
Manifests contain credential names, not values.
Picoo clears unrelated environment variables.
MCP requires explicit operation, network, and auth permission.
Narrow, short-lived credentials reduce the impact of mistakes.