Secrets and runtime variables

OpenComputer secrets are write-only values used by declared outbound connections. Plaintext values are not included in source bundles, prompts, deployment manifests, runtime environment variables, logs, or API responses.

Declare a connectionCopy Anchor Link

import { bearer, defineConnection, useSecret } from "@opencomputer/agent";

const github = defineConnection({
  id: "github-api",
  origin: "https://api.github.com",
  methods: ["GET"],
  pathPrefix: "/repos/",
  headers: {
    Authorization: bearer(useSecret("GITHUB_TOKEN")),
  },
});

export default function Agent() {
  return "Use GitHub when it helps answer the request.";
}

The origin must use HTTPS. OpenComputer rejects hard-coded sensitive headers such as Authorization, Cookie, and X-API-Key; reference a managed secret instead.

Tools can make requests through the same connection:

const response = await github.fetch("/repos/opencomputer/example");
const repository = await response.json();

Only a relative path is accepted. OpenComputer checks the declared origin, path prefix, method, agent, and environment before sending the outbound request.

Synchronize development secretsCopy Anchor Link

Place development-only values in opencomputer/.env.local:

GITHUB_TOKEN=github_pat_...

opencomputer doctor compares these local names with useSecret() references and .env.example. Upload is always explicit; deployment never opens a value prompt. The CLI infers the allowed origins from the source declaration.

Variables without a matching declaration are skipped. OpenComputer never grants an unmatched value access to every host, and removing a local variable does not delete its cloud value. Use opencomputer secrets remove when deletion is intentional. The starter ignores opencomputer/.env.local and includes an opencomputer/.env.example file for documenting required names without values.

Set a project secretCopy Anchor Link

Secrets belong to a cloud project. Link explicitly first with opencomputer link --project <id|slug> or --create-project <name>.

printf %s "$GITHUB_TOKEN" | npx --package @opencomputer/cli opencomputer secrets set GITHUB_TOKEN --value-stdin

The CLI accepts the value only from piped standard input. When run from an initialized project it infers allowed origins from connections that reference the secret.

Project secrets are available to declared connections in every agent in the project. Create an agent-specific override when one agent needs a different credential:

printf %s "$GITHUB_TOKEN" | npx --package @opencomputer/cli opencomputer secrets set GITHUB_TOKEN --value-stdin --agent current

Secrets are separate for development and production:

printf %s "$GITHUB_TOKEN" | npx --package @opencomputer/cli opencomputer secrets set GITHUB_TOKEN --value-stdin --environment production
npx --package @opencomputer/cli opencomputer secrets list --environment development
npx --package @opencomputer/cli opencomputer secrets remove GITHUB_TOKEN --environment development

List output contains metadata such as the name, scope, environment, and allowed origins. Secret values are never returned.

Agent runtime variablesCopy Anchor Link

Use an agent runtime variable when code or a command must receive a value as a normal environment variable. Configure it in the Agent runtime variables section of the project’s Secrets page, or with the CLI:

printf %s "$DATABASE_URL" | npx --package @opencomputer/cli opencomputer env set DATABASE_URL --value-stdin
npx --package @opencomputer/cli opencomputer env list --environment development
npx --package @opencomputer/cli opencomputer env remove DATABASE_URL

The CLI reads new values only from piped standard input. Runtime variables can apply to the whole project or override one agent with --agent current, and development and production values are separate. No declaration in agent source is needed.

OpenComputer stores these values encrypted and never returns them through the dashboard or management API. A newly started agent runtime receives the resolved values in its process environment, so agent code, tools, commands, and child processes can read them. Because the agent can access the plaintext, runtime variables are appropriate for personal-agent credentials such as DATABASE_URL, but they do not provide the destination isolation of managed secrets. Restart a running agent runtime after changing a value.

Security guaranteesCopy Anchor Link

For managed secrets, OpenComputer resolves the declared connection and scoped secret for each request. The credential is attached only after the destination, method, path, agent, project, and environment have been validated. The value is never added to the agent’s source bundle, prompt, browser application, or logs.