> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencomputer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets and runtime variables

> Configure managed outbound credentials and agent runtime environment 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 connection

```tsx theme={null}
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:

```tsx theme={null}
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 secrets

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

```dotenv theme={null}
GITHUB_TOKEN=github_pat_...
```

When `npm run dev` starts, the CLI considers only names referenced by
`useSecret()` in a `defineConnection()` declaration. It infers the allowed
origins from those declarations and asks before uploading each newly discovered
secret. Changed values are synchronized while the development process is
running.

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 secret

Secrets belong to a cloud project. If the app is not linked yet, this command
first asks you to select or create one, then continues setting the secret.

```bash theme={null}
npx --package @opencomputer/cli opencomputer secrets set GITHUB_TOKEN
```

The CLI reads the value from a hidden prompt. When run from an initialized
project it can infer allowed origins from connections that reference the
secret. For CI, provide the value through standard input rather than a command
argument.

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:

```bash theme={null}
npx --package @opencomputer/cli opencomputer secrets set GITHUB_TOKEN --agent current
```

Secrets are separate for `development` and `production`:

```bash theme={null}
npx --package @opencomputer/cli opencomputer secrets set GITHUB_TOKEN --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 variables

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:

```bash theme={null}
npx --package @opencomputer/cli opencomputer env set DATABASE_URL
npx --package @opencomputer/cli opencomputer env list --environment development
npx --package @opencomputer/cli opencomputer env remove DATABASE_URL
```

The CLI reads new values from a hidden prompt. 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 guarantees

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.